@wvdsh/sdk-js 1.3.14 → 1.3.16

package/dist/index.d.ts

@@ -91,6 +91,8 @@ type UpsertedLeaderboardEntry = FunctionReturnType<typeof api.sdk.leaderboards.u
     userId: GenericId<"users">;
     username: string;
     userAvatarUrl?: string;
+    submittedScore: number;
+    submittedRank: number;
 };
 type WavedashEvent = (typeof WavedashEvents)[keyof typeof WavedashEvents];
 interface WavedashConfig {
@@ -625,36 +627,53 @@ declare class HeartbeatManager extends WavedashManager {
     private deviceFingerprintReady;
     private testConnectionInterval;
     private heartbeatInterval;
+    private gamepadPollInterval;
+    private inactivityTimeout;
     private isConnected;
     private sentDisconnectedEvent;
     private disconnectedAt;
     private lastHeartbeatTime;
+    private lastInputResetAt;
     private heartbeatInFlight;
     private isFirstTick;
     private readonly TEST_CONNECTION_INTERVAL_MS;
     private readonly DISCONNECTED_TIMEOUT_MS;
+    private readonly INACTIVITY_TIMEOUT_MS;
+    private readonly INPUT_THROTTLE_MS;
+    private readonly GAMEPAD_POLL_INTERVAL_MS;
+    private readonly GAMEPAD_AXIS_DEADZONE;
     private cachedPresenceData;
     constructor(sdk: WavedashSDK);
-    /** Start heartbeat and connection-check intervals */
+    /**
+     * Start (or refresh) the heartbeat. Idempotent: if intervals are already
+     * running this just reschedules the inactivity timer. No-op if the game
+     * hasn't loaded yet or the tab is hidden.
+     */
     start(): void;
-    /** Stop heartbeat and connection-check intervals */
+    /** Stop the heartbeat and clear the inactivity timer. Idempotent. */
     stop(): void;
-    /** Full teardown — stops intervals and removes all listeners */
-    destroy(): void;
-    private handleVisibilityChange;
-    private tickHeartbeat;
-    private sendHeartbeat;
     /**
      * 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>;
+    isCurrentlyConnected(): boolean;
+    /** Full teardown — stops intervals and removes all listeners */
+    destroy(): void;
+    private tickHeartbeat;
+    private sendHeartbeat;
+    private handleVisibilityChange;
+    private handleUserInput;
+    /**
+     * Polls connected gamepads; any pressed button or out-of-deadzone axis
+     * counts as user activity and (re)starts the heartbeat.
+     */
+    private pollGamepads;
     /**
      * Tests the connection to the backend
      */
     private testConnection;
-    isCurrentlyConnected(): boolean;
 }
 
 declare class GameEventManager extends WavedashManager {
@@ -750,6 +769,20 @@ declare class AudioManager extends WavedashManager {
     private mutationObserver;
     constructor(sdk: WavedashSDK);
     isMuted(): boolean;
+    /**
+     * Ask the host to mute (true) or unmute (false). Resolves to `true` if the
+     * host applied the change, `false` otherwise — notably, the host rejects an
+     * unmute when the user muted the game from the Wavedash UI, so games can't
+     * override an explicit user mute. The resulting state arrives via the usual
+     * MUTE_CHANGED broadcast, so `isMuted()` updates independently of this result.
+     */
+    requestMute(muted: boolean): Promise<boolean>;
+    /**
+     * Toggle mute. Like `requestMute`, the host may reject the unmute half of a
+     * toggle if the user muted from the Wavedash UI. Resolves to `true` if the
+     * host applied the change.
+     */
+    toggleMute(): Promise<boolean>;
     private handleMute;
     /**
      * Track a media element and (if SDK is currently muted) silence it.
@@ -1004,6 +1037,22 @@ declare class WavedashSDK extends EventTarget {
      * a user gesture handler when entering fullscreen.
      */
     toggleFullscreen(): Promise<boolean>;
+    /**
+     * Whether the game is currently muted. Mirrored from the Wavedash host page,
+     * which owns the mute control so its UI button and the game stay in sync.
+     */
+    isMuted(): boolean;
+    /**
+     * Ask the host to mute (true) or unmute (false). Resolves to `true` if the
+     * change was applied, `false` if it was rejected — the host won't let the
+     * game unmute when the user has muted from the Wavedash UI.
+     */
+    requestMute(muted: boolean): Promise<boolean>;
+    /**
+     * Toggle mute. Resolves to `true` if the change was applied, `false` if it
+     * was rejected (e.g. trying to unmute over an explicit user mute).
+     */
+    toggleMute(): Promise<boolean>;
     getUser(): SDKUser;
     /**
      * Get a username. Returns the logged in user's username if no ID is passed.

package/dist/index.js

@@ -1172,7 +1172,12 @@ var LeaderboardManager = class extends WavedashManager {
       this.updateCachedTotalEntries(leaderboardId, result.totalEntries);
     }
     return {
+      // Where your current leaderboard standing ranks
       ...result.entry,
+      // Where the submission itself ranks
+      submittedScore: result.submission.score,
+      submittedRank: result.submission.globalRank,
+      // User info
       userId: this.sdk.wavedashUser.id,
       username: this.sdk.wavedashUser.username,
       userAvatarUrl: this.sdk.wavedashUser.avatarUrl
@@ -2698,20 +2703,31 @@ import {
   HEARTBEAT,
   IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE2
 } from "@wvdsh/api";
+var INPUT_LISTENER_OPTS = {
+  passive: true,
+  capture: true
+};
 var HeartbeatManager = class extends WavedashManager {
   constructor(sdk) {
     super(sdk);
     this.deviceFingerprint = void 0;
     this.testConnectionInterval = null;
     this.heartbeatInterval = null;
+    this.gamepadPollInterval = null;
+    this.inactivityTimeout = null;
     this.isConnected = false;
     this.sentDisconnectedEvent = false;
     this.disconnectedAt = null;
     this.lastHeartbeatTime = 0;
+    this.lastInputResetAt = 0;
     this.heartbeatInFlight = false;
     this.isFirstTick = true;
     this.TEST_CONNECTION_INTERVAL_MS = 1e3;
     this.DISCONNECTED_TIMEOUT_MS = 9e4;
+    this.INACTIVITY_TIMEOUT_MS = 30 * 60 * 1e3;
+    this.INPUT_THROTTLE_MS = 1e3;
+    this.GAMEPAD_POLL_INTERVAL_MS = 1e3;
+    this.GAMEPAD_AXIS_DEADZONE = 0.2;
     this.cachedPresenceData = {};
     this.handleVisibilityChange = () => {
       if (document.visibilityState === "visible") {
@@ -2720,19 +2736,53 @@ var HeartbeatManager = class extends WavedashManager {
         this.stop();
       }
     };
+    this.handleUserInput = () => {
+      const now = Date.now();
+      if (now - this.lastInputResetAt < this.INPUT_THROTTLE_MS) return;
+      this.lastInputResetAt = now;
+      this.start();
+    };
     this.isConnected = this.sdk.convexClient.client.connectionState().isWebSocketConnected;
     document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    window.addEventListener(
+      "keydown",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
+    window.addEventListener(
+      "pointerdown",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
+    window.addEventListener(
+      "pointermove",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
+    window.addEventListener("wheel", this.handleUserInput, INPUT_LISTENER_OPTS);
+    this.gamepadPollInterval = setInterval(() => {
+      this.pollGamepads();
+    }, this.GAMEPAD_POLL_INTERVAL_MS);
     this.deviceFingerprintReady = this.sdk.iframeMessenger.requestFromParent(IFRAME_MESSAGE_TYPE2.GET_DEVICE_FINGERPRINT).then((fingerprint) => {
       this.deviceFingerprint = fingerprint;
     }).catch(() => {
     });
   }
-  /** Start heartbeat and connection-check intervals */
+  /**
+   * Start (or refresh) the heartbeat. Idempotent: if intervals are already
+   * running this just reschedules the inactivity timer. No-op if the game
+   * hasn't loaded yet or the tab is hidden.
+   */
   start() {
-    if (!this.sdk.gameLoaded) {
-      return;
-    }
-    this.stop();
+    if (!this.sdk.gameLoaded) return;
+    if (document.visibilityState !== "visible") return;
+    if (this.inactivityTimeout !== null) {
+      clearTimeout(this.inactivityTimeout);
+    }
+    this.inactivityTimeout = setTimeout(() => {
+      this.stop();
+    }, this.INACTIVITY_TIMEOUT_MS);
+    if (this.heartbeatInterval !== null) return;
     if (this.isFirstTick) {
       void this.deviceFingerprintReady.then(() => {
         if (!this.sdk.gameLoaded || !this.isFirstTick) return;
@@ -2748,8 +2798,12 @@ var HeartbeatManager = class extends WavedashManager {
       this.testConnection();
     }, this.TEST_CONNECTION_INTERVAL_MS);
   }
-  /** Stop heartbeat and connection-check intervals */
+  /** Stop the heartbeat and clear the inactivity timer. Idempotent. */
   stop() {
+    if (this.inactivityTimeout !== null) {
+      clearTimeout(this.inactivityTimeout);
+      this.inactivityTimeout = null;
+    }
     if (this.heartbeatInterval !== null) {
       clearInterval(this.heartbeatInterval);
       this.heartbeatInterval = null;
@@ -2759,14 +2813,62 @@ var HeartbeatManager = class extends WavedashManager {
       this.testConnectionInterval = null;
     }
   }
+  /**
+   * 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 {
+      this.cachedPresenceData = data;
+      await this.sdk.convexClient.mutation(api7.sdk.presence.heartbeat, {
+        data,
+        deviceFingerprint: this.deviceFingerprint
+      });
+      return true;
+    } catch (error) {
+      logger.error(`Error updating presence: ${error}`);
+      return false;
+    }
+  }
+  isCurrentlyConnected() {
+    return this.isConnected;
+  }
   /** Full teardown — stops intervals and removes all listeners */
   destroy() {
     this.stop();
+    if (this.gamepadPollInterval !== null) {
+      clearInterval(this.gamepadPollInterval);
+      this.gamepadPollInterval = null;
+    }
     document.removeEventListener(
       "visibilitychange",
       this.handleVisibilityChange
     );
+    window.removeEventListener(
+      "keydown",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
+    window.removeEventListener(
+      "pointerdown",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
+    window.removeEventListener(
+      "pointermove",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
+    window.removeEventListener(
+      "wheel",
+      this.handleUserInput,
+      INPUT_LISTENER_OPTS
+    );
   }
+  // =================
+  // Private functions
+  // =================
   tickHeartbeat() {
     const timeSinceLastHeartbeat = Date.now() - this.lastHeartbeatTime;
     const needsReestablish = this.isFirstTick || timeSinceLastHeartbeat >= HEARTBEAT.CLIENT_REESTABLISH_THRESHOLD_MS;
@@ -2796,21 +2898,22 @@ var HeartbeatManager = class extends WavedashManager {
     });
   }
   /**
-   * Updates user presence in the backend.
-   * @param data - Data to send to the backend
-   * @returns true if the presence was updated successfully
+   * Polls connected gamepads; any pressed button or out-of-deadzone axis
+   * counts as user activity and (re)starts the heartbeat.
    */
-  async updateUserPresence(data) {
-    try {
-      this.cachedPresenceData = data;
-      await this.sdk.convexClient.mutation(api7.sdk.presence.heartbeat, {
-        data,
-        deviceFingerprint: this.deviceFingerprint
-      });
-      return true;
-    } catch (error) {
-      logger.error(`Error updating presence: ${error}`);
-      return false;
+  pollGamepads() {
+    if (typeof navigator === "undefined" || !navigator.getGamepads) return;
+    const pads = navigator.getGamepads();
+    for (const pad of pads) {
+      if (!pad) continue;
+      if (pad.buttons.some((b) => b.pressed)) {
+        this.start();
+        return;
+      }
+      if (pad.axes.some((a) => Math.abs(a) > this.GAMEPAD_AXIS_DEADZONE)) {
+        this.start();
+        return;
+      }
     }
   }
   /**
@@ -2857,9 +2960,6 @@ var HeartbeatManager = class extends WavedashManager {
       logger.error("Error testing connection:", error);
     }
   }
-  isCurrentlyConnected() {
-    return this.isConnected;
-  }
 };
 
 // src/services/gameEvents.ts
@@ -3101,6 +3201,31 @@ var AudioManager = class extends WavedashManager {
   isMuted() {
     return this._isMuted;
   }
+  /**
+   * Ask the host to mute (true) or unmute (false). Resolves to `true` if the
+   * host applied the change, `false` otherwise — notably, the host rejects an
+   * unmute when the user muted the game from the Wavedash UI, so games can't
+   * override an explicit user mute. The resulting state arrives via the usual
+   * MUTE_CHANGED broadcast, so `isMuted()` updates independently of this result.
+   */
+  async requestMute(muted) {
+    const response = await this.sdk.iframeMessenger.requestFromParent(
+      IFRAME_MESSAGE_TYPE5.SET_MUTE,
+      { muted }
+    );
+    return response.success;
+  }
+  /**
+   * Toggle mute. Like `requestMute`, the host may reject the unmute half of a
+   * toggle if the user muted from the Wavedash UI. Resolves to `true` if the
+   * host applied the change.
+   */
+  async toggleMute() {
+    const response = await this.sdk.iframeMessenger.requestFromParent(
+      IFRAME_MESSAGE_TYPE5.TOGGLE_MUTE
+    );
+    return response.success;
+  }
   /**
    * Track a media element and (if SDK is currently muted) silence it.
    * Idempotent — safe to call multiple times for the same element.
@@ -3673,11 +3798,11 @@ var WavedashSDK = class extends EventTarget {
       expectAuth: true
     });
     this.gameCloudId = sdkConfig.gameCloudId;
+    this.iframeMessenger = iframeMessenger;
     this.convexClient.setAuth(
       ({ forceRefreshToken }) => this.getAuthToken(forceRefreshToken)
     );
     this.wavedashUser = sdkConfig.wavedashUser;
-    this.iframeMessenger = iframeMessenger;
     this.ugcHost = sdkConfig.ugcHost;
     this.uploadsHost = sdkConfig.uploadsHost;
     this.swMessenger = new SwMessenger();
@@ -3881,6 +4006,31 @@ var WavedashSDK = class extends EventTarget {
   async toggleFullscreen() {
     return this.fullscreenManager.toggleFullscreen();
   }
+  // =====
+  // Audio
+  // =====
+  /**
+   * Whether the game is currently muted. Mirrored from the Wavedash host page,
+   * which owns the mute control so its UI button and the game stay in sync.
+   */
+  isMuted() {
+    return this.audioManager.isMuted();
+  }
+  /**
+   * Ask the host to mute (true) or unmute (false). Resolves to `true` if the
+   * change was applied, `false` if it was rejected — the host won't let the
+   * game unmute when the user has muted from the Wavedash UI.
+   */
+  async requestMute(muted) {
+    return this.audioManager.requestMute(muted);
+  }
+  /**
+   * Toggle mute. Resolves to `true` if the change was applied, `false` if it
+   * was rejected (e.g. trying to unmute over an explicit user mute).
+   */
+  async toggleMute() {
+    return this.audioManager.toggleMute();
+  }
   // ============
   // User methods
   // ============

package/package.json

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