@mentra/miniapp 0.3.0-dev.0 → 3.1.0-dev.10

package/dist/modules/events.js

@@ -9,7 +9,7 @@
  *   - session.imu.onHeadPosition(...)
  *   - session.location.onUpdate(...)
  *   - session.glasses.onBattery(...) / onConnection(...)
- *   - session.phone.onNotification(...) / onCalendarEvent(...) / onBattery(...)
+ *   - session.phone.notifications.on(...) / session.phone.onBattery(...)
  *
  * This module's only public method is `subscribe(rawStreamType, handler)` —
  * a forward-compat escape hatch for new event types not yet wrapped on a
@@ -36,8 +36,10 @@ export class EventManager {
     constructor(session) {
         this.session = session;
         this.emitter = new EventEmitter();
-        /** Stream -> ref count. Outbound SUBSCRIBE is sent when refs transition 0↔1. */
+        /** Stream -> ref count. Outbound SUBSCRIBE tracks active streams and routing changes. */
         this.refCounts = new Map();
+        /** Transcription stream -> refs that require on-device-only processing. */
+        this.forceLocalRefCounts = new Map();
     }
     /**
      * Generic subscribe. `stream` is the raw wire value, including any language
@@ -51,42 +53,73 @@ export class EventManager {
      * via a separate envelope `type`; the EventManager only routes them
      * locally.
      */
-    subscribe(stream, handler) {
-        this.emitter.on(stream, handler);
+    subscribe(stream, handler, options = {}) {
         const isInternal = stream.startsWith("_");
+        const forceLocal = options.forceLocal === true && stream.startsWith(`${MiniappStreamType.TRANSCRIPTION}:`);
+        const listener = (data, route) => {
+            if (stream.startsWith(`${MiniappStreamType.TRANSCRIPTION}:`)) {
+                // Hosts that predate routed transcription events omit `route`. Treat
+                // those events as the default/cloud path so a forceLocal listener can
+                // never accidentally receive cloud text.
+                if (forceLocal ? route !== "forceLocal" && route !== "all" : route === "forceLocal")
+                    return;
+            }
+            handler(data);
+        };
+        this.emitter.on(stream, listener);
         if (!isInternal) {
             const before = this.refCounts.get(stream) ?? 0;
             this.refCounts.set(stream, before + 1);
-            if (before === 0) {
+            const forceLocalBefore = this.forceLocalRefCounts.get(stream) ?? 0;
+            const defaultBefore = before - forceLocalBefore;
+            if (forceLocal)
+                this.forceLocalRefCounts.set(stream, forceLocalBefore + 1);
+            if (before === 0 || (forceLocal && forceLocalBefore === 0) || (!forceLocal && defaultBefore === 0)) {
                 this.sendSubscriptionUpdate();
             }
         }
         return () => {
-            this.emitter.off(stream, handler);
+            this.emitter.off(stream, listener);
             if (isInternal)
                 return;
             const current = this.refCounts.get(stream) ?? 0;
+            const forceLocalCurrent = this.forceLocalRefCounts.get(stream) ?? 0;
+            let subscriptionChanged = current <= 1;
             if (current <= 1) {
                 this.refCounts.delete(stream);
-                this.sendSubscriptionUpdate();
             }
             else {
                 this.refCounts.set(stream, current - 1);
             }
+            if (forceLocal) {
+                if (forceLocalCurrent <= 1) {
+                    this.forceLocalRefCounts.delete(stream);
+                    subscriptionChanged = true;
+                }
+                else {
+                    this.forceLocalRefCounts.set(stream, forceLocalCurrent - 1);
+                }
+            }
+            else if (current - forceLocalCurrent <= 1) {
+                subscriptionChanged = true;
+            }
+            if (subscriptionChanged)
+                this.sendSubscriptionUpdate();
         };
     }
     /** Unsubscribe every handler on every stream this EventManager owns. */
     unsubscribeAll() {
         this.emitter.removeAllListeners();
         this.refCounts.clear();
+        this.forceLocalRefCounts.clear();
         this.sendSubscriptionUpdate();
     }
     // -------------------------------------------------------------------------
     // Internal — called by MiniappSession when EVENT arrives from phone
     // -------------------------------------------------------------------------
     /** @internal */
-    _forwardEvent(stream, data) {
-        this.emitter.emit(stream, data);
+    _forwardEvent(stream, data, transcriptionRoute) {
+        this.emitter.emit(stream, data, transcriptionRoute);
         // Wildcard fan-out: handlers register under wildcard patterns
         // ("transcription:auto", "translation:*:<target>", …) but the host
         // delivers events under the CONCRETE stream key
@@ -95,7 +128,7 @@ export class EventManager {
         // LocalMiniappRuntime.forwardEvent matches on the host side —
         // otherwise a wildcard subscriber never fires.
         if (stream.startsWith("transcription:") && stream !== "transcription:auto") {
-            this.emitter.emit("transcription:auto", data);
+            this.emitter.emit("transcription:auto", data, transcriptionRoute);
         }
         else if (stream.startsWith("translation:")) {
             const parts = stream.split(":");
@@ -113,7 +146,19 @@ export class EventManager {
         }
     }
     sendSubscriptionUpdate() {
-        const subscriptions = Array.from(this.refCounts.keys()).map((stream) => stream === MiniappStreamType.LOCATION_UPDATE ? { stream: "location_stream", rate: "realtime" } : stream);
+        const subscriptions = Array.from(this.refCounts.keys()).map((stream) => {
+            if (stream === MiniappStreamType.LOCATION_UPDATE)
+                return { stream: "location_stream", rate: "realtime" };
+            const forceLocalRefs = this.forceLocalRefCounts.get(stream) ?? 0;
+            if (forceLocalRefs === 0)
+                return stream;
+            const totalRefs = this.refCounts.get(stream) ?? 0;
+            return {
+                stream,
+                forceLocal: true,
+                ...(totalRefs > forceLocalRefs ? { includeCloud: true } : {}),
+            };
+        });
         this.session.sendOneShot({
             type: MiniappRequestType.SUBSCRIBE,
             subscriptions,

package/dist/modules/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/modules/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAwIjE,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,OAAO,YAAY;IAKvB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAJnC,YAAO,GAAG,IAAI,YAAY,EAAE,CAAA;QAC7C,gFAAgF;QAC/D,cAAS,GAAG,IAAI,GAAG,EAAkB,CAAA;IAEC,CAAC;IAExD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAc,EAAE,OAAgC;QACxD,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAChC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;QACzC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,CAAA;YACtC,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjB,IAAI,CAAC,sBAAsB,EAAE,CAAA;YAC/B,CAAC;QACH,CAAC;QACD,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;YACjC,IAAI,UAAU;gBAAE,OAAM;YACtB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAC/C,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;gBACjB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAC7B,IAAI,CAAC,sBAAsB,EAAE,CAAA;YAC/B,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,CAAA;YACzC,CAAC;QACH,CAAC,CAAA;IACH,CAAC;IAED,wEAAwE;IACxE,cAAc;QACZ,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAA;QACjC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;QACtB,IAAI,CAAC,sBAAsB,EAAE,CAAA;IAC/B,CAAC;IAED,4EAA4E;IAC5E,oEAAoE;IACpE,4EAA4E;IAE5E,gBAAgB;IAChB,aAAa,CAAC,MAAc,EAAE,IAAa;QACzC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAE/B,8DAA8D;QAC9D,mEAAmE;QACnE,gDAAgD;QAChD,iEAAiE;QACjE,4DAA4D;QAC5D,8DAA8D;QAC9D,+CAA+C;QAC/C,IAAI,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,IAAI,MAAM,KAAK,oBAAoB,EAAE,CAAC;YAC3E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAA;QAC/C,CAAC;aAAM,IAAI,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,CAAC,kBAAkB,CAAC,CAAC,CAAA;YACtD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAA;gBAChC,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAA;gBAC/B,QAAQ,CAAC,GAAG,CAAC,iBAAiB,MAAM,EAAE,CAAC,CAAA;gBACvC,QAAQ,CAAC,GAAG,CAAC,eAAe,MAAM,IAAI,CAAC,CAAA;YACzC,CAAC;YACD,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA,CAAC,kCAAkC;YAC1D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAEO,sBAAsB;QAC5B,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CACrE,MAAM,KAAK,iBAAiB,CAAC,eAAe,CAAC,CAAC,CAAC,EAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAC,CAAC,CAAC,CAAC,MAAM,CACtG,CAAA;QACD,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;YACvB,IAAI,EAAE,kBAAkB,CAAC,SAAS;YAClC,aAAa;SACd,CAAC,CAAA;IACJ,CAAC;CACF"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/modules/events.ts"],"names":[],"mappings":"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"}

package/dist/modules/glasses.d.ts

@@ -24,5 +24,13 @@ export declare class GlassesModule {
      * line shown in the setup prompt (e.g. "Streaming needs your glasses on Wi-Fi").
      */
     requestWifiSetup(reason?: string): Promise<void>;
+    /**
+     * Enable or disable Wi-Fi ADB (wireless debugging) on Mentra Live.
+     * Persisted on the glasses; boot applies the saved preference (default off).
+     *
+     * SYSTEM-only — rejects with `NOT_PERMITTED` unless this miniapp is a system
+     * app. Third-party miniapps must not expose wireless debugging controls.
+     */
+    setWifiAdbState(enabled: boolean): Promise<void>;
 }
 //# sourceMappingURL=glasses.d.ts.map

package/dist/modules/glasses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glasses.d.ts","sourceRoot":"","sources":["../../src/modules/glasses.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAC,MAAM,UAAU,CAAA;AAElF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,aAAa;IAI9D,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,aAAa;IAIpE;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,aAAa;IAIxD;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMvD"}
+{"version":3,"file":"glasses.d.ts","sourceRoot":"","sources":["../../src/modules/glasses.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAC,MAAM,UAAU,CAAA;AAElF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,aAAa;IAI9D,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,aAAa;IAIpE;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,aAAa;IAIxD;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD;;;;;;OAMG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAMvD"}

package/dist/modules/glasses.js

@@ -35,5 +35,18 @@ export class GlassesModule {
             reason,
         });
     }
+    /**
+     * Enable or disable Wi-Fi ADB (wireless debugging) on Mentra Live.
+     * Persisted on the glasses; boot applies the saved preference (default off).
+     *
+     * SYSTEM-only — rejects with `NOT_PERMITTED` unless this miniapp is a system
+     * app. Third-party miniapps must not expose wireless debugging controls.
+     */
+    async setWifiAdbState(enabled) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.SET_WIFI_ADB_STATE,
+            enabled,
+        });
+    }
 }
 //# sourceMappingURL=glasses.js.map

package/dist/modules/glasses.js.map

@@ -1 +1 @@
-{"version":3,"file":"glasses.js","sourceRoot":"","sources":["../../src/modules/glasses.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAIjE,MAAM,OAAO,aAAa;IACxB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD,SAAS,CAAC,OAAoC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,eAAe,EAAE,OAAkC,CAAC,CAAA;IACvG,CAAC;IAED,YAAY,CAAC,OAAuC;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,kBAAkB,EAAE,OAAkC,CAAC,CAAA;IAC1G,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAiC;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,YAAY,EAAE,OAAkC,CAAC,CAAA;IACpG,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,gBAAgB,CAAC,MAAe;QACpC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,kBAAkB;YAC3C,MAAM;SACP,CAAC,CAAA;IACJ,CAAC;CACF"}
+{"version":3,"file":"glasses.js","sourceRoot":"","sources":["../../src/modules/glasses.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAIjE,MAAM,OAAO,aAAa;IACxB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD,SAAS,CAAC,OAAoC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,eAAe,EAAE,OAAkC,CAAC,CAAA;IACvG,CAAC;IAED,YAAY,CAAC,OAAuC;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,kBAAkB,EAAE,OAAkC,CAAC,CAAA;IAC1G,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAiC;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,YAAY,EAAE,OAAkC,CAAC,CAAA;IACpG,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,gBAAgB,CAAC,MAAe;QACpC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,kBAAkB;YAC3C,MAAM;SACP,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,eAAe,CAAC,OAAgB;QACpC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,kBAAkB;YAC3C,OAAO;SACR,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/languages.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Language validation at the SDK boundary (issue 021, WP2).
+ *
+ * The registry itself lives in `@mentra/cloud-protocol/languages` (single
+ * source of truth shared with the cloud). This module re-exports the types so
+ * miniapps import everything from `@mentra/miniapp`, and adds the throwing
+ * validators the typed module surfaces (`transcription.*`, `translation.*`)
+ * call on every language parameter.
+ *
+ * Contract (design doc docs/issues/021-typed-language-subscriptions):
+ *   - Valid by construction: params are typed as literal unions, so TS users
+ *     get autocomplete and compile errors.
+ *   - Loud at runtime: JS users (or `any` casts) get a thrown
+ *     `MiniappValidationError` with a suggestion, never silent fallback.
+ *   - Canonical on the wire: bare codes ("fr") canonicalize to their default
+ *     tag ("fr-FR") before becoming stream keys, so the phone/cloud only ever
+ *     see registry tags.
+ */
+import { isTranscriptionLanguage, SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES } from "@mentra/cloud-protocol/languages";
+import type { LanguageHint, TranscriptionLanguage } from "@mentra/cloud-protocol/languages";
+export { SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES, isTranscriptionLanguage };
+export type { LanguageHint, TranscriptionLanguage };
+/**
+ * Thrown synchronously by SDK methods when a parameter fails validation.
+ * Deliberately a hard throw (not a warning, not a silent default): an invalid
+ * language previously produced a subscription that silently transcribed the
+ * wrong language or silently never spoke (OS-1746).
+ */
+export declare class MiniappValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Canonicalize a subscription language or throw. Accepts registry tags
+ * ("fr-FR") and bare registry codes ("fr" -> "fr-FR").
+ */
+export declare function requireTranscriptionLanguage(value: string, param: string): TranscriptionLanguage;
+/**
+ * Normalize a language hint to the bare code the STT provider accepts, or
+ * throw. Accepts bare codes ("fr") and registry tags ("fr-FR" -> "fr").
+ */
+export declare function requireLanguageHint(value: string, param: string): LanguageHint;
+//# sourceMappingURL=languages.d.ts.map

package/dist/modules/languages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languages.d.ts","sourceRoot":"","sources":["../../src/modules/languages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,uBAAuB,EAIvB,wBAAwB,EACxB,iCAAiC,EAClC,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAC,YAAY,EAAE,qBAAqB,EAAC,MAAM,kCAAkC,CAAA;AAEzF,OAAO,EAAC,wBAAwB,EAAE,iCAAiC,EAAE,uBAAuB,EAAC,CAAA;AAC7F,YAAY,EAAC,YAAY,EAAE,qBAAqB,EAAC,CAAA;AAEjD;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAShG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAO9E"}

package/dist/modules/languages.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Language validation at the SDK boundary (issue 021, WP2).
+ *
+ * The registry itself lives in `@mentra/cloud-protocol/languages` (single
+ * source of truth shared with the cloud). This module re-exports the types so
+ * miniapps import everything from `@mentra/miniapp`, and adds the throwing
+ * validators the typed module surfaces (`transcription.*`, `translation.*`)
+ * call on every language parameter.
+ *
+ * Contract (design doc docs/issues/021-typed-language-subscriptions):
+ *   - Valid by construction: params are typed as literal unions, so TS users
+ *     get autocomplete and compile errors.
+ *   - Loud at runtime: JS users (or `any` casts) get a thrown
+ *     `MiniappValidationError` with a suggestion, never silent fallback.
+ *   - Canonical on the wire: bare codes ("fr") canonicalize to their default
+ *     tag ("fr-FR") before becoming stream keys, so the phone/cloud only ever
+ *     see registry tags.
+ */
+import { isTranscriptionLanguage, suggestTranscriptionLanguage, toLanguageHint, toTranscriptionLanguage, SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES, } from "@mentra/cloud-protocol/languages";
+export { SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES, isTranscriptionLanguage };
+/**
+ * Thrown synchronously by SDK methods when a parameter fails validation.
+ * Deliberately a hard throw (not a warning, not a silent default): an invalid
+ * language previously produced a subscription that silently transcribed the
+ * wrong language or silently never spoke (OS-1746).
+ */
+export class MiniappValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MiniappValidationError";
+    }
+}
+/**
+ * Canonicalize a subscription language or throw. Accepts registry tags
+ * ("fr-FR") and bare registry codes ("fr" -> "fr-FR").
+ */
+export function requireTranscriptionLanguage(value, param) {
+    const canonical = toTranscriptionLanguage(value);
+    if (canonical)
+        return canonical;
+    const suggestion = suggestTranscriptionLanguage(value);
+    throw new MiniappValidationError(`${param}: unknown language ${JSON.stringify(value)}` +
+        (suggestion ? ` — did you mean ${JSON.stringify(suggestion)}?` : "") +
+        ` Supported values are BCP-47 tags from SUPPORTED_TRANSCRIPTION_LANGUAGES (e.g. "en-US", "fr-FR").`);
+}
+/**
+ * Normalize a language hint to the bare code the STT provider accepts, or
+ * throw. Accepts bare codes ("fr") and registry tags ("fr-FR" -> "fr").
+ */
+export function requireLanguageHint(value, param) {
+    const hint = toLanguageHint(value);
+    if (hint)
+        return hint;
+    throw new MiniappValidationError(`${param}: unknown language hint ${JSON.stringify(value)}. ` +
+        `Hints are bare ISO 639-1 codes from SUPPORTED_LANGUAGE_HINTS (e.g. "en", "fr").`);
+}
+//# sourceMappingURL=languages.js.map

package/dist/modules/languages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"languages.js","sourceRoot":"","sources":["../../src/modules/languages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EAAC,wBAAwB,EAAE,iCAAiC,EAAE,uBAAuB,EAAC,CAAA;AAG7F;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAa,EAAE,KAAa;IACvE,MAAM,SAAS,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAA;IAChD,IAAI,SAAS;QAAE,OAAO,SAAS,CAAA;IAC/B,MAAM,UAAU,GAAG,4BAA4B,CAAC,KAAK,CAAC,CAAA;IACtD,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,sBAAsB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;QACnD,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,mGAAmG,CACtG,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,KAAa;IAC9D,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAClC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IACrB,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI;QAC1D,iFAAiF,CACpF,CAAA;AACH,CAAC"}

package/dist/modules/mic.d.ts

@@ -31,6 +31,23 @@ export declare class MicModule {
      * (PCM or LC3, base64-encoded).
      */
     onAudioChunk(handler: (data: AudioChunkData) => void): UnsubscribeFn;
+    /**
+     * Temporarily override glasses-side voice activity detection (GX8002) for
+     * this miniapp's lifetime. When disabled, mic gating falls back to the
+     * loudness gate only (if it is enabled). The Mentra App's configured value
+     * is restored when this miniapp disconnects.
+     *
+     * Requires `MICROPHONE` in the miniapp manifest.
+     */
+    setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Temporarily override the center-mic loudness gate ("Barrier") for this
+     * miniapp's lifetime. It blocks quiet/self-talk audio independent of VAD.
+     * The Mentra App's configured value is restored when this miniapp disconnects.
+     *
+     * Requires `MICROPHONE` in the miniapp manifest.
+     */
+    setLoudnessGateEnabled(enabled: boolean): Promise<void>;
     /**
      * Tear down every subscription this module owns. Useful when a component
      * is unmounting and wants to free everything at once without tracking

package/dist/modules/mic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mic.d.ts","sourceRoot":"","sources":["../../src/modules/mic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAE,OAAO,EAAC,MAAM,UAAU,CAAA;AAEpE,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;gBAErB,OAAO,EAAE,cAAc;IAEpD;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,aAAa;IAIhE;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,aAAa;IAIpE;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAWZ,mEAAmE;IACnE,IAAI,aAAa,IAAI,OAAO,CAE3B;IAID,OAAO,CAAC,KAAK;CAOd"}
+{"version":3,"file":"mic.d.ts","sourceRoot":"","sources":["../../src/modules/mic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAE,OAAO,EAAC,MAAM,UAAU,CAAA;AAEpE,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;gBAErB,OAAO,EAAE,cAAc;IAEpD;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,aAAa;IAIhE;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,aAAa;IAIpE;;;;;;;OAOG;IACH,gCAAgC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjE;;;;;;OAMG;IACH,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAWZ,mEAAmE;IACnE,IAAI,aAAa,IAAI,OAAO,CAE3B;IAID,OAAO,CAAC,KAAK;CAOd"}

package/dist/modules/mic.js

@@ -14,7 +14,7 @@
  * subscriptions to succeed; the phone runtime rejects with
  * PERMISSION_NOT_DECLARED otherwise.
  */
-import { MiniappStreamType } from "../protocol";
+import { MiniappRequestType, MiniappStreamType } from "../protocol";
 export class MicModule {
     constructor(session) {
         this.session = session;
@@ -35,6 +35,33 @@ export class MicModule {
     onAudioChunk(handler) {
         return this.track(this.session._subscribe(MiniappStreamType.AUDIO_CHUNK, handler));
     }
+    /**
+     * Temporarily override glasses-side voice activity detection (GX8002) for
+     * this miniapp's lifetime. When disabled, mic gating falls back to the
+     * loudness gate only (if it is enabled). The Mentra App's configured value
+     * is restored when this miniapp disconnects.
+     *
+     * Requires `MICROPHONE` in the miniapp manifest.
+     */
+    setVoiceActivityDetectionEnabled(enabled) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.MIC_SET_VAD_ENABLED,
+            enabled,
+        });
+    }
+    /**
+     * Temporarily override the center-mic loudness gate ("Barrier") for this
+     * miniapp's lifetime. It blocks quiet/self-talk audio independent of VAD.
+     * The Mentra App's configured value is restored when this miniapp disconnects.
+     *
+     * Requires `MICROPHONE` in the miniapp manifest.
+     */
+    setLoudnessGateEnabled(enabled) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.MIC_SET_LOUDNESS_GATE_ENABLED,
+            enabled,
+        });
+    }
     /**
      * Tear down every subscription this module owns. Useful when a component
      * is unmounting and wants to free everything at once without tracking

package/dist/modules/mic.js.map

@@ -1 +1 @@
-{"version":3,"file":"mic.js","sourceRoot":"","sources":["../../src/modules/mic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAI7C,MAAM,OAAO,SAAS;IAIpB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAHpD,wEAAwE;QACvD,WAAM,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEK,CAAC;IAExD;;;OAGG;IACH,eAAe,CAAC,OAAgC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,GAAG,EAAE,OAAkC,CAAC,CAAC,CAAA;IACvG,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,OAAuC;QAClD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAkC,CAAC,CAAC,CAAA;IAC/G,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,CAAC,EAAE,CAAA;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAED,mEAAmE;IACnE,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,YAAY,CAAC,CAAA;IAC1D,CAAC;IAED,2EAA2E;IAEnE,KAAK,CAAC,KAAoB;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACtB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACzB,KAAK,EAAE,CAAA;QACT,CAAC,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"mic.js","sourceRoot":"","sources":["../../src/modules/mic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAIjE,MAAM,OAAO,SAAS;IAIpB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAHpD,wEAAwE;QACvD,WAAM,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEK,CAAC;IAExD;;;OAGG;IACH,eAAe,CAAC,OAAgC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,GAAG,EAAE,OAAkC,CAAC,CAAC,CAAA;IACvG,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,OAAuC;QAClD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAkC,CAAC,CAAC,CAAA;IAC/G,CAAC;IAED;;;;;;;OAOG;IACH,gCAAgC,CAAC,OAAgB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACpC,IAAI,EAAE,kBAAkB,CAAC,mBAAmB;YAC5C,OAAO;SACR,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;OAMG;IACH,sBAAsB,CAAC,OAAgB;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACpC,IAAI,EAAE,kBAAkB,CAAC,6BAA6B;YACtD,OAAO;SACR,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,CAAC,EAAE,CAAA;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAED,mEAAmE;IACnE,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,YAAY,CAAC,CAAA;IAC1D,CAAC;IAED,2EAA2E;IAEnE,KAAK,CAAC,KAAoB;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACtB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACzB,KAAK,EAAE,CAAA;QACT,CAAC,CAAA;IACH,CAAC;CACF"}

package/dist/modules/miniapps.d.ts

@@ -17,6 +17,8 @@ export interface MiniappActionInfo {
      * to an MCP tool `inputSchema`. Undefined for actions that take no params.
      */
     parameters?: Record<string, unknown>;
+    /** JSON-Schema descriptor for the structured value returned by the action. */
+    outputSchema?: Record<string, unknown>;
 }
 /**
  * Hardware compatibility for a listed miniapp. Structurally mirrors the host's

package/dist/modules/miniapps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"miniapps.d.ts","sourceRoot":"","sources":["../../src/modules/miniapps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AAEzC,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,OAAO,CAAA;IACrB,eAAe,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACtD,eAAe,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,oBAAoB,CAAA;IACnC,6DAA6D;IAC7D,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;;OAIG;IACG,IAAI,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAQ9D;;;;;;OAMG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,yCAAyC;IACnC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM/C"}
+{"version":3,"file":"miniapps.d.ts","sourceRoot":"","sources":["../../src/modules/miniapps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AAEzC,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,OAAO,CAAA;IACrB,eAAe,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACtD,eAAe,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,oBAAoB,CAAA;IACnC,6DAA6D;IAC7D,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;;OAIG;IACG,IAAI,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAQ9D;;;;;;OAMG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,yCAAyC;IACnC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM/C"}

package/dist/modules/miniapps.js.map

@@ -1 +1 @@
-{"version":3,"file":"miniapps.js","sourceRoot":"","sources":["../../src/modules/miniapps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AA0C9C,MAAM,OAAO,cAAc;IACzB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,IAA0B;QACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAgB;YAC3D,IAAI,EAAE,kBAAkB,CAAC,aAAa;YACtC,mBAAmB,EAAE,IAAI,EAAE,mBAAmB,IAAI,KAAK;SACxD,CAAC,CAAA;QACF,OAAO,MAAM,IAAI,EAAE,CAAA;IACrB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,WAAmB;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,cAAc;YACvC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;IAED,yCAAyC;IACzC,KAAK,CAAC,IAAI,CAAC,WAAmB;QAC5B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,aAAa;YACtC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;CACF"}
+{"version":3,"file":"miniapps.js","sourceRoot":"","sources":["../../src/modules/miniapps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AA4C9C,MAAM,OAAO,cAAc;IACzB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,IAA0B;QACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAgB;YAC3D,IAAI,EAAE,kBAAkB,CAAC,aAAa;YACtC,mBAAmB,EAAE,IAAI,EAAE,mBAAmB,IAAI,KAAK;SACxD,CAAC,CAAA;QACF,OAAO,MAAM,IAAI,EAAE,CAAA;IACrB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,WAAmB;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,cAAc;YACvC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;IAED,yCAAyC;IACzC,KAAK,CAAC,IAAI,CAAC,WAAmB;QAC5B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,aAAa;YACtC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/phone.d.ts

@@ -4,7 +4,7 @@
  * Mirrors cloud SDK v3's PhoneManager structure. Sub-namespaced by concern:
  *
  *   session.phone.notifications.{on, hasPermission, stop}
- *   session.phone.calendar.{on, hasPermission, stop}
+ *   session.phone.calendar.{listEvents, hasPermission}
  *   session.phone.onBattery(...)                          // stays flat
  *
  * Imperative phone-OS calls (share, openUrl, copyToClipboard, download) live
@@ -16,7 +16,7 @@
  * subscribing on iOS is a no-op even though the API is present.
  */
 import { MiniappSession } from "../session";
-import type { BatteryData, CalendarEventData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn } from "./events";
+import type { BatteryData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn } from "./events";
 declare class TrackedSubs {
     private readonly unsubs;
     protected track(unsub: UnsubscribeFn): UnsubscribeFn;
@@ -39,10 +39,44 @@ export declare class PhoneNotificationsModule extends TrackedSubs {
     /** True iff `READ_NOTIFICATIONS` is declared in the miniapp's manifest. */
     get hasPermission(): boolean;
 }
-export declare class PhoneCalendarModule extends TrackedSubs {
+export interface CalendarListOptions {
+    /** Inclusive start of the query window. */
+    startsAt: string | Date;
+    /** Exclusive end of the query window. Must be after startsAt. */
+    endsAt: string | Date;
+    /** Maximum events to return. Defaults to 50 and may not exceed 100. */
+    limit?: number;
+}
+export interface CalendarEvent {
+    /** Stable occurrence id, unique across calendars and recurring instances. */
+    id: string;
+    calendarId: string;
+    title: string;
+    /** ISO 8601 start time. All-day events preserve their calendar timezone offset. */
+    startsAt: string;
+    /** ISO 8601 end time. All-day events preserve their calendar timezone offset. */
+    endsAt: string;
+    timezone?: string;
+    allDay: boolean;
+    location?: string;
+    notes?: string;
+    url?: string;
+    /** Deduplicated HTTPS links found in the event URL, location, and notes. */
+    links: string[];
+}
+export interface CalendarListResult {
+    events: CalendarEvent[];
+    /** True when more matching events existed than the requested limit. */
+    truncated: boolean;
+}
+export declare class PhoneCalendarModule {
     private readonly session;
     constructor(session: MiniappSession);
-    on(handler: (data: CalendarEventData) => void): UnsubscribeFn;
+    /**
+     * Read calendar events in a bounded window. CALENDAR must be declared in
+     * miniapp.json and granted before the miniapp opens.
+     */
+    listEvents(options: CalendarListOptions): Promise<CalendarListResult>;
     /** True iff `CALENDAR` is declared in the miniapp's manifest. */
     get hasPermission(): boolean;
 }

package/dist/modules/phone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../src/modules/phone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,EACrB,aAAa,EACd,MAAM,UAAU,CAAA;AAEjB,cAAM,WAAW;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa;IAQpD,IAAI,IAAI,IAAI;CAUb;AAED,qBAAa,wBAAyB,SAAQ,WAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAIpD,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,GAAG,aAAa;IAMjE;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,yBAAyB,KAAK,IAAI,GAAG,aAAa;IAS9E,2EAA2E;IAC3E,IAAI,aAAa,IAAI,OAAO,CAE3B;CACF;AAED,qBAAa,mBAAoB,SAAQ,WAAW;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAIpD,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,GAAG,aAAa;IAM7D,iEAAiE;IACjE,IAAI,aAAa,IAAI,OAAO,CAE3B;CACF;AAED,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,SAAgB,aAAa,EAAE,wBAAwB,CAAA;IACvD,SAAgB,QAAQ,EAAE,mBAAmB,CAAA;gBAEhB,OAAO,EAAE,cAAc;IAKpD;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,aAAa;CAG/D"}
+{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../src/modules/phone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,WAAW,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,aAAa,EAAC,MAAM,UAAU,CAAA;AAE1G,cAAM,WAAW;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa;IAQpD,IAAI,IAAI,IAAI;CAUb;AAED,qBAAa,wBAAyB,SAAQ,WAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAIpD,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,GAAG,aAAa;IAIjE;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,yBAAyB,KAAK,IAAI,GAAG,aAAa;IAM9E,2EAA2E;IAC3E,IAAI,aAAa,IAAI,OAAO,CAE3B;CACF;AAED,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,iEAAiE;IACjE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAWrE,iEAAiE;IACjE,IAAI,aAAa,IAAI,OAAO,CAE3B;CACF;AAQD,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,SAAgB,aAAa,EAAE,wBAAwB,CAAA;IACvD,SAAgB,QAAQ,EAAE,mBAAmB,CAAA;gBAEhB,OAAO,EAAE,cAAc;IAKpD;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,aAAa;CAG/D"}

package/dist/modules/phone.js

@@ -4,7 +4,7 @@
  * Mirrors cloud SDK v3's PhoneManager structure. Sub-namespaced by concern:
  *
  *   session.phone.notifications.{on, hasPermission, stop}
- *   session.phone.calendar.{on, hasPermission, stop}
+ *   session.phone.calendar.{listEvents, hasPermission}
  *   session.phone.onBattery(...)                          // stays flat
  *
  * Imperative phone-OS calls (share, openUrl, copyToClipboard, download) live
@@ -15,7 +15,7 @@
  * notification-dismiss callbacks to apps (Apple privacy restriction);
  * subscribing on iOS is a no-op even though the API is present.
  */
-import { MiniappStreamType } from "../protocol";
+import { MiniappRequestType, MiniappStreamType } from "../protocol";
 class TrackedSubs {
     constructor() {
         this.unsubs = new Set();
@@ -64,19 +64,35 @@ export class PhoneNotificationsModule extends TrackedSubs {
         return this.session._hasManifestPermission("READ_NOTIFICATIONS");
     }
 }
-export class PhoneCalendarModule extends TrackedSubs {
+export class PhoneCalendarModule {
     constructor(session) {
-        super();
         this.session = session;
     }
-    on(handler) {
-        return this.track(this.session._subscribe(MiniappStreamType.CALENDAR_EVENT, handler));
+    /**
+     * Read calendar events in a bounded window. CALENDAR must be declared in
+     * miniapp.json and granted before the miniapp opens.
+     */
+    listEvents(options) {
+        const startsAt = normalizeCalendarDate(options?.startsAt, "startsAt");
+        const endsAt = normalizeCalendarDate(options?.endsAt, "endsAt");
+        return this.session.sendRequest({
+            type: MiniappRequestType.CALENDAR_LIST_EVENTS,
+            startsAt,
+            endsAt,
+            ...(options.limit === undefined ? {} : { limit: options.limit }),
+        });
     }
     /** True iff `CALENDAR` is declared in the miniapp's manifest. */
     get hasPermission() {
         return this.session._hasManifestPermission("CALENDAR");
     }
 }
+function normalizeCalendarDate(value, field) {
+    const date = value instanceof Date ? value : new Date(value ?? "");
+    if (Number.isNaN(date.getTime()))
+        throw new TypeError(`${field} must be a valid Date or ISO 8601 string`);
+    return date.toISOString();
+}
 export class PhoneModule {
     constructor(session) {
         this.session = session;

package/dist/modules/phone.js.map

@@ -1 +1 @@
-{"version":3,"file":"phone.js","sourceRoot":"","sources":["../../src/modules/phone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAU7C,MAAM,WAAW;IAAjB;QACmB,WAAM,GAAG,IAAI,GAAG,EAAiB,CAAA;IAoBpD,CAAC;IAlBW,KAAK,CAAC,KAAoB;QAClC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACtB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACzB,KAAK,EAAE,CAAA;QACT,CAAC,CAAA;IACH,CAAC;IAED,IAAI;QACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,CAAC,EAAE,CAAA;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACvD,YAA6B,OAAuB;QAClD,KAAK,EAAE,CAAA;QADoB,YAAO,GAAP,OAAO,CAAgB;IAEpD,CAAC;IAED,EAAE,CAAC,OAA8C;QAC/C,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,kBAAkB,EAAE,OAAkC,CAAC,CAClG,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAkD;QAC5D,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,OAAO,CAAC,UAAU,CACrB,iBAAiB,CAAC,4BAA4B,EAC9C,OAAkC,CACnC,CACF,CAAA;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,oBAAoB,CAAC,CAAA;IAClE,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IAClD,YAA6B,OAAuB;QAClD,KAAK,EAAE,CAAA;QADoB,YAAO,GAAP,OAAO,CAAgB;IAEpD,CAAC;IAED,EAAE,CAAC,OAA0C;QAC3C,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,cAAc,EAAE,OAAkC,CAAC,CAC9F,CAAA;IACH,CAAC;IAED,iEAAiE;IACjE,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAA;IACxD,CAAC;CACF;AAED,MAAM,OAAO,WAAW;IAItB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAClD,IAAI,CAAC,aAAa,GAAG,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAA;QAC1D,IAAI,CAAC,QAAQ,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAA;IAClD,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,OAAoC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,aAAa,EAAE,OAAkC,CAAC,CAAA;IACrG,CAAC;CACF"}
+{"version":3,"file":"phone.js","sourceRoot":"","sources":["../../src/modules/phone.ts"],"names":[],"mappings":"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"}

package/dist/modules/speaker.d.ts

@@ -45,6 +45,17 @@ export interface SpeakOptions {
     voice_settings?: Record<string, unknown>;
     volume?: number;
     stopOtherAudio?: boolean;
+    /**
+     * Normalize display-oriented markup and symbols into natural spoken words.
+     * Defaults to true. Set false when exact characters must reach the TTS engine.
+     */
+    enableSanitization?: boolean;
+    /**
+     * Force this call to use on-device offline TTS, skipping cloud TTS
+     * entirely — even when cloud is connected. Rejects with `TTS_LOCAL_UNAVAILABLE`
+     * if the offline model isn't ready instead of falling back to cloud.
+     */
+    forceLocal?: boolean;
 }
 export interface SpeakResult {
     /** True if playback completed; false if playback was interrupted. */
@@ -136,6 +147,7 @@ export declare class SpeakerModule {
      * TTS failures: `TTS_TEXT_TOO_LONG`, `TTS_INVALID_VOICE`, `TTS_UPSTREAM_ERROR`.
      */
     speak(text: string, options?: SpeakOptions): Promise<SpeakResult>;
+    speak(sentences: string[], options?: SpeakOptions): Promise<SpeakResult>;
     /**
      * Open a live PCM output stream (16-bit LE) to the phone's audio playback
      * service. Use from the background to play audio that arrives in chunks

package/dist/modules/speaker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"speaker.d.ts","sourceRoot":"","sources":["../../src/modules/speaker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"speaker.d.ts","sourceRoot":"","sources":["../../src/modules/speaker.ts"],"names":[],"mappings":"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"}