@wvdsh/sdk-js 1.3.12 → 1.3.13

package/dist/index.d.ts

@@ -627,6 +627,7 @@ declare class HeartbeatManager extends WavedashManager {
     private isFirstTick;
     private readonly TEST_CONNECTION_INTERVAL_MS;
     private readonly DISCONNECTED_TIMEOUT_MS;
+    private cachedPresenceData;
     constructor(sdk: WavedashSDK);
     /** Start heartbeat and connection-check intervals */
     start(): void;
@@ -638,11 +639,11 @@ declare class HeartbeatManager extends WavedashManager {
     private tickHeartbeat;
     private sendHeartbeat;
     /**
-     * Updates user presence in the backend
+     * Updates user presence in the backend.
      * @param data - Data to send to the backend
      * @returns true if the presence was updated successfully
      */
-    updateUserPresence(data?: Record<string, string | number | boolean | null>): Promise<boolean>;
+    updateUserPresence(data: Record<string, string | number | boolean | null>): Promise<boolean>;
     /**
      * Tests the connection to the backend
      */
@@ -713,6 +714,47 @@ declare class OverlayManager extends WavedashManager {
     private handleKeyDown;
 }
 
+/**
+ * AudioManager
+ *
+ * Mutes & unmutes the game in response to MUTE_CHANGED iframe messages, without
+ * the game needing to know anything about it.
+ *
+ * Web Audio: subclass `AudioContext` so `ctx.destination` resolves to a master
+ * GainNode that we control. The master gain wires to the real native destination,
+ * so `node.connect(ctx.destination)` and any other game code is unaffected.
+ *
+ * HTML Media (`<audio>`/`<video>`): override `HTMLMediaElement.prototype.muted`
+ * to record the game's intended state, but write `true` to the underlying element
+ * whenever the SDK is muted. Tracked elements come from three sources:
+ *  1. Pre-existing DOM media (`querySelectorAll`)
+ *  2. `new Audio()` constructor shim (covers detached SFX)
+ *  3. MutationObserver for any media added to the DOM later (covers innerHTML,
+ *     framework rendering, createElement + append, etc.)
+ */
+declare class AudioManager extends WavedashManager {
+    private _isMuted;
+    private contexts;
+    private elements;
+    private intendedMuted;
+    private originalAudioContext;
+    private originalWebKitAudioContext;
+    private originalAudio;
+    private originalMutedDescriptor;
+    private mutationObserver;
+    constructor(sdk: WavedashSDK);
+    isMuted(): boolean;
+    private handleMute;
+    /**
+     * Track a media element and (if SDK is currently muted) silence it.
+     * Idempotent — safe to call multiple times for the same element.
+     */
+    private trackElement;
+    private installShims;
+    private shimAudioContextClass;
+    destroy(): void;
+}
+
 /**
  * Friends service
  *
@@ -898,6 +940,7 @@ declare class WavedashSDK extends EventTarget {
     p2pManager: P2PManager;
     fullscreenManager: FullscreenManager;
     overlayManager: OverlayManager;
+    audioManager: AudioManager;
     private managers;
     private gameplayJwt;
     private gameplayJwtPromise;
@@ -1162,11 +1205,16 @@ declare class WavedashSDK extends EventTarget {
     inviteUserToLobby(lobbyId: GenericId<"lobbies">, userId: GenericId<"users">): Promise<WavedashResponse<boolean>>;
     getLobbyInviteLink(copyToClipboard?: boolean): Promise<WavedashResponse<string>>;
     /**
-     * Updates rich user presence so friends can see what the player is doing in game
-     * @param data Game data to send to the backend
+     * Updates rich user presence so friends can see what the player is doing in game.
+     * Supported keys:
+     *   `status`  — one-line activity shown as the primary line (e.g. "Traveling in a group")
+     *   `details` — secondary context shown beneath the status (e.g. current zone or mode)
+     *
+     * Pass an empty dictionary to clear all presence fields.
+     * @param data Presence fields to update.
      * @returns true if the presence was updated successfully
      */
-    updateUserPresence(data?: Record<string, string | number | boolean | null>): Promise<WavedashResponse<boolean>>;
+    updateUserPresence(data: Record<string, string | number | boolean | null>): Promise<WavedashResponse<boolean>>;
     private isGodot;
     private formatResponse;
     private ensureInit;

package/dist/index.js

@@ -2709,6 +2709,7 @@ var HeartbeatManager = class extends WavedashManager {
     this.isFirstTick = true;
     this.TEST_CONNECTION_INTERVAL_MS = 1e3;
     this.DISCONNECTED_TIMEOUT_MS = 9e4;
+    this.cachedPresenceData = {};
     this.handleVisibilityChange = () => {
       if (document.visibilityState === "visible") {
         this.start();
@@ -2778,7 +2779,7 @@ var HeartbeatManager = class extends WavedashManager {
     this.heartbeatInFlight = true;
     this.sdk.convexClient.mutation(api7.sdk.presence.heartbeat, {
       ...reestablish ? {
-        data: { forceUpdate: true },
+        data: this.cachedPresenceData,
         deviceFingerprint: this.deviceFingerprint
       } : {}
     }).then((accepted) => {
@@ -2792,15 +2793,15 @@ var HeartbeatManager = class extends WavedashManager {
     });
   }
   /**
-   * Updates user presence in the backend
+   * Updates user presence in the backend.
    * @param data - Data to send to the backend
    * @returns true if the presence was updated successfully
    */
   async updateUserPresence(data) {
     try {
-      const dataToSend = data ?? { forceUpdate: true };
+      this.cachedPresenceData = data;
       await this.sdk.convexClient.mutation(api7.sdk.presence.heartbeat, {
-        data: dataToSend,
+        data,
         deviceFingerprint: this.deviceFingerprint
       });
       return true;
@@ -3028,6 +3029,211 @@ var OverlayManager = class extends WavedashManager {
   }
 };
 
+// src/services/audio.ts
+import { IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE5 } from "@wvdsh/api";
+var WeakRefSet = class {
+  constructor() {
+    this.set = /* @__PURE__ */ new Set();
+  }
+  add(value) {
+    for (const ref of this.set) {
+      if (ref.deref() === value) return;
+    }
+    this.set.add(new WeakRef(value));
+  }
+  forEach(callback) {
+    for (const ref of this.set) {
+      const v = ref.deref();
+      if (v === void 0) this.set.delete(ref);
+      else callback(v);
+    }
+  }
+  clear() {
+    this.set.clear();
+  }
+};
+var AudioManager = class extends WavedashManager {
+  constructor(sdk) {
+    super(sdk);
+    this._isMuted = false;
+    // Web Audio contexts and their master gain nodes
+    this.contexts = /* @__PURE__ */ new Map();
+    // HTML media elements we know about + their game-intended muted state
+    this.elements = new WeakRefSet();
+    this.intendedMuted = /* @__PURE__ */ new WeakMap();
+    // Originals (restored on destroy)
+    this.originalAudioContext = null;
+    this.originalWebKitAudioContext = null;
+    this.originalAudio = null;
+    this.originalMutedDescriptor = null;
+    this.mutationObserver = null;
+    this.handleMute = (data) => {
+      if (this._isMuted === data.isMuted) return;
+      this._isMuted = data.isMuted;
+      logger.debug(`[AudioManager] muted=${this._isMuted}`);
+      const target = this._isMuted ? 0 : 1;
+      this.contexts.forEach((gain, ctx) => {
+        const now = ctx.currentTime;
+        gain.gain.cancelScheduledValues(now);
+        gain.gain.setValueAtTime(gain.gain.value, now);
+        gain.gain.linearRampToValueAtTime(target, now + 0.05);
+      });
+      const setMutedNative = this.originalMutedDescriptor?.set;
+      if (setMutedNative) {
+        this.elements.forEach((el) => {
+          const intended = this.intendedMuted.get(el) ?? false;
+          setMutedNative.call(el, this._isMuted ? true : intended);
+        });
+      }
+    };
+    this.installShims();
+    this.sdk.iframeMessenger.addEventListener(
+      IFRAME_MESSAGE_TYPE5.MUTE_CHANGED,
+      this.handleMute
+    );
+  }
+  isMuted() {
+    return this._isMuted;
+  }
+  /**
+   * Track a media element and (if SDK is currently muted) silence it.
+   * Idempotent — safe to call multiple times for the same element.
+   */
+  trackElement(el) {
+    if (this.intendedMuted.has(el)) return;
+    const getMuted = this.originalMutedDescriptor?.get;
+    const setMuted = this.originalMutedDescriptor?.set;
+    const current = getMuted ? getMuted.call(el) : el.muted;
+    this.intendedMuted.set(el, current);
+    this.elements.add(el);
+    if (this._isMuted && !current && setMuted) {
+      setMuted.call(el, true);
+    }
+  }
+  installShims() {
+    if (typeof window === "undefined") return;
+    if (window.AudioContext) {
+      this.originalAudioContext = window.AudioContext;
+      window.AudioContext = this.shimAudioContextClass(window.AudioContext);
+    }
+    const win = window;
+    if (win.webkitAudioContext) {
+      this.originalWebKitAudioContext = win.webkitAudioContext;
+      win.webkitAudioContext = this.shimAudioContextClass(win.webkitAudioContext);
+    }
+    if (window.Audio) {
+      const OriginalAudio = window.Audio;
+      this.originalAudio = OriginalAudio;
+      ((manager) => {
+        const Shimmed = function(src) {
+          const audio = new OriginalAudio(src);
+          manager.trackElement(audio);
+          return audio;
+        };
+        Shimmed.prototype = OriginalAudio.prototype;
+        window.Audio = Shimmed;
+      })(this);
+    }
+    if (typeof document !== "undefined") {
+      document.querySelectorAll("audio, video").forEach((el) => {
+        this.trackElement(el);
+      });
+      this.mutationObserver = new MutationObserver((mutations) => {
+        for (const m of mutations) {
+          m.addedNodes.forEach((node) => {
+            if (node instanceof HTMLMediaElement) {
+              this.trackElement(node);
+            } else if (node instanceof HTMLElement) {
+              node.querySelectorAll("audio, video").forEach((el) => {
+                this.trackElement(el);
+              });
+            }
+          });
+        }
+      });
+      this.mutationObserver.observe(document.documentElement, {
+        childList: true,
+        subtree: true
+      });
+    }
+    this.originalMutedDescriptor = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "muted") ?? null;
+    const original = this.originalMutedDescriptor;
+    if (original?.get && original?.set) {
+      ((manager) => {
+        Object.defineProperty(HTMLMediaElement.prototype, "muted", {
+          configurable: true,
+          get() {
+            const intended = manager.intendedMuted.get(this);
+            return intended !== void 0 ? intended : original.get.call(this);
+          },
+          set(value) {
+            manager.intendedMuted.set(this, value);
+            manager.elements.add(this);
+            original.set.call(this, manager._isMuted ? true : value);
+          }
+        });
+      })(this);
+    }
+  }
+  shimAudioContextClass(Original) {
+    return /* @__PURE__ */ ((manager) => class extends Original {
+      constructor(opts) {
+        super(opts);
+        const masterGain = this.createGain();
+        masterGain.connect(this.destination);
+        masterGain.gain.setValueAtTime(
+          manager._isMuted ? 0 : 1,
+          this.currentTime
+        );
+        Object.defineProperty(this, "destination", {
+          configurable: true,
+          get() {
+            return masterGain;
+          }
+        });
+        manager.contexts.set(this, masterGain);
+      }
+      close() {
+        manager.contexts.delete(this);
+        return super.close();
+      }
+    })(this);
+  }
+  destroy() {
+    this.sdk.iframeMessenger.removeEventListener(
+      IFRAME_MESSAGE_TYPE5.MUTE_CHANGED,
+      this.handleMute
+    );
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = null;
+    }
+    if (typeof window !== "undefined") {
+      if (this.originalAudioContext) {
+        window.AudioContext = this.originalAudioContext;
+      }
+      const win = window;
+      if (this.originalWebKitAudioContext && win.webkitAudioContext) {
+        win.webkitAudioContext = this.originalWebKitAudioContext;
+      }
+      if (this.originalAudio) {
+        window.Audio = this.originalAudio;
+      }
+    }
+    if (this.originalMutedDescriptor) {
+      Object.defineProperty(
+        HTMLMediaElement.prototype,
+        "muted",
+        this.originalMutedDescriptor
+      );
+    }
+    this.contexts.clear();
+    this.elements.clear();
+    this.intendedMuted = /* @__PURE__ */ new WeakMap();
+    super.destroy();
+  }
+};
+
 // src/services/friends.ts
 import { api as api8 } from "@wvdsh/api";
 
@@ -3289,7 +3495,7 @@ var SwMessenger = class {
 };
 
 // src/index.ts
-import { IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE5, UrlParams } from "@wvdsh/api";
+import { IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE6, UrlParams } from "@wvdsh/api";
 
 // src/utils/validation.ts
 var CONVEX_ID_REGEX = /^[0-9a-z]{31,37}$/;
@@ -3333,6 +3539,13 @@ var vRecord = (value, path) => {
       `${path}: expected plain object, got ${describeValue(value)}`
     );
   }
+  for (const [key, val] of Object.entries(value)) {
+    if (typeof val === "object" && val !== null) {
+      throw new Error(
+        `${path}: expected flat record with no nested objects, but key "${key}" contains ${describeValue(val)}`
+      );
+    }
+  }
   return value;
 };
 function vId(tableName) {
@@ -3377,7 +3590,12 @@ function vUnion(...variants) {
 }
 function vObject(shape) {
   return (value, path) => {
-    const obj = vRecord(value, path);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new Error(
+        `${path}: expected plain object, got ${describeValue(value)}`
+      );
+    }
+    const obj = value;
     for (const key of Object.keys(obj)) {
       if (!(key in shape)) {
         throw new Error(`${path}: unrecognized property "${key}"`);
@@ -3468,6 +3686,7 @@ var WavedashSDK = class extends EventTarget {
     this.gameEventManager = new GameEventManager(this);
     this.fullscreenManager = new FullscreenManager(this);
     this.overlayManager = new OverlayManager(this);
+    this.audioManager = new AudioManager(this);
     this.managers = [
       this.p2pManager,
       this.lobbyManager,
@@ -3479,7 +3698,8 @@ var WavedashSDK = class extends EventTarget {
       this.friendsManager,
       this.gameEventManager,
       this.fullscreenManager,
-      this.overlayManager
+      this.overlayManager,
+      this.audioManager
     ];
     this.friendsManager.cacheUsers([
       {
@@ -3611,7 +3831,7 @@ var WavedashSDK = class extends EventTarget {
       [progress]
     );
     this.clearSetupWarning();
-    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE5.PROGRESS_UPDATE, {
+    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE6.PROGRESS_UPDATE, {
       progress
     });
   }
@@ -3620,7 +3840,7 @@ var WavedashSDK = class extends EventTarget {
     if (this.gameFinishedLoading) return;
     this.gameFinishedLoading = true;
     this.heartbeatManager.start();
-    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE5.LOADING_COMPLETE, {});
+    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE6.LOADING_COMPLETE, {});
     this.overlayManager.takeFocus();
   }
   get gameLoaded() {
@@ -4368,15 +4588,34 @@ var WavedashSDK = class extends EventTarget {
   // User Presence
   // ==============================
   /**
-   * Updates rich user presence so friends can see what the player is doing in game
-   * @param data Game data to send to the backend
+   * Updates rich user presence so friends can see what the player is doing in game.
+   * Supported keys:
+   *   `status`  — one-line activity shown as the primary line (e.g. "Traveling in a group")
+   *   `details` — secondary context shown beneath the status (e.g. current zone or mode)
+   * 
+   * Pass an empty dictionary to clear all presence fields.
+   * @param data Presence fields to update.
    * @returns true if the presence was updated successfully
    */
   async updateUserPresence(data) {
+    if (typeof data === "string") {
+      const raw = data;
+      try {
+        data = JSON.parse(raw);
+      } catch (error) {
+        const message = `updateUserPresence: invalid JSON: ${raw}`;
+        logger.error(message, error);
+        return this.formatResponse({
+          success: false,
+          data: null,
+          message
+        });
+      }
+    }
     return this.apiCall(
       this.heartbeatManager,
       "updateUserPresence",
-      [["data", vOptional(vRecord)]],
+      [["data", vRecord]],
       data
     );
   }
@@ -4467,7 +4706,7 @@ var WavedashSDK = class extends EventTarget {
         throw new Error(`Failed to refresh gameplay token: ${response.status}`);
       }
       this.gameplayJwt = await response.text();
-      iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE5.GAMEPLAY_JWT_READY, {
+      iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE6.GAMEPLAY_JWT_READY, {
         gameplayJwt: this.gameplayJwt
       });
       this.swMessenger.postToServiceWorker({
@@ -4503,7 +4742,7 @@ var WavedashSDK = class extends EventTarget {
   }
   setupSessionEndListeners() {
     iframeMessenger.addEventListener(
-      IFRAME_MESSAGE_TYPE5.END_SESSION,
+      IFRAME_MESSAGE_TYPE6.END_SESSION,
       () => this.destroy()
     );
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wvdsh/sdk-js",
-  "version": "1.3.12",
+  "version": "1.3.13",
   "type": "module",
   "description": "Wavedash JavaScript SDK",
   "main": "./dist/client.js",
@@ -49,8 +49,8 @@
     "typescript-eslint": "^8.52.0"
   },
   "dependencies": {
-    "@wvdsh/api": "^0.1.27",
-    "convex": "^1.38.0",
+    "@wvdsh/api": "^0.1.28",
+    "convex": "^1.39.1",
     "lodash.throttle": "^4.1.1"
   }
 }