@wvdsh/sdk-js 1.3.10 → 1.3.11

package/dist/index.d.ts

@@ -385,14 +385,25 @@ declare class FileSystemManager extends WavedashManager {
      */
     deleteRemoteFile(filePath: string): Promise<string>;
     /**
-     * Downloads a remote file to a local location
+     * Downloads a remote file to a local location.
+     * Throws on failure; the error message is the server's HTTP status (e.g. "404 (Not Found)")
+     * or a network-level description if the server didn't respond. See also: {@link remoteFileExists}
      * @param filePath - The path of the remote file to download
      * @returns The path of the local file that the remote file was downloaded to
      */
     downloadRemoteFile(filePath: string): Promise<string>;
     /**
-     * Lists each file in a remote directory, including its subdirectories
-     * Returns only file paths, no directory paths
+     * Checks whether a remote file exists by issuing a HEAD request.
+     * Does NOT throw for the "file does not exist" case — returns false.
+     * Throws only for real errors (network failure, auth failure, server error).
+     * @param filePath - The path of the remote file to check
+     * @returns true if the remote file exists, false otherwise
+     */
+    remoteFileExists(filePath: string): Promise<boolean>;
+    /**
+     * Lists each file in a remote directory, including its subdirectories.
+     * Returns only file paths, no directory paths.
+     * An empty or non-existent directory returns an empty array — not an error.
      * @param path - The path of the remote directory to list
      * @returns A list of metadata for each file in the remote directory
      */
@@ -401,7 +412,7 @@ declare class FileSystemManager extends WavedashManager {
     writeLocalFile(filePath: string, data: Uint8Array): Promise<boolean>;
     readLocalFile(filePath: string): Promise<Uint8Array | null>;
     upload(presignedUploadUrl: string, filePath: string): Promise<boolean>;
-    download(url: string, filePath: string): Promise<boolean>;
+    download(url: string, filePath: string): Promise<void>;
     private getRemoteStorageOrigin;
     private getRemoteStorageUrl;
     private uploadFromIndexedDb;
@@ -1009,12 +1020,19 @@ declare class WavedashSDK extends EventTarget {
      */
     deleteRemoteFile(filePath: string): Promise<WavedashResponse<string>>;
     /**
-     * Downloads a remote file to a local location
+     * Downloads a remote file to a local location.
+     * Returns success=false (with the server status in `message`) if the file
+     * doesn't exist or any other error occurs. See also: {@link remoteFileExists}
      * @param filePath - The path of the remote file to download
-     * @param downloadTo - Optionally provide a path to download the file to, defaults to the same path as the remote file
      * @returns The path of the local file that the remote file was downloaded to
      */
     downloadRemoteFile(filePath: string): Promise<WavedashResponse<string>>;
+    /**
+     * Checks whether a remote file exists. Sends a lightweight HEAD request to check for existence.
+     * @param filePath - The path of the remote file to check
+     * @returns true if the remote file exists, false if it does not.
+     */
+    remoteFileExists(filePath: string): Promise<WavedashResponse<boolean>>;
     /**
      * Uploads a local file to remote storage
      * @param filePath - The path of the local file to upload

package/dist/index.js

@@ -270,18 +270,14 @@ var _LobbyManager = class _LobbyManager extends WavedashManager {
   }
   getLobbyUsers(lobbyId) {
     if (this.lobbyId !== lobbyId) {
-      logger.error(
-        "Must be a member of the lobby to access user list"
-      );
+      logger.error("Must be a member of the lobby to access user list");
       return [];
     }
     return this.lobbyUsers;
   }
   getHostId(lobbyId) {
     if (this.lobbyId !== lobbyId) {
-      logger.error(
-        "Must be a member of the lobby to access the host ID"
-      );
+      logger.error("Must be a member of the lobby to access the host ID");
       return null;
     }
     return this.lobbyHostId;
@@ -467,9 +463,7 @@ var _LobbyManager = class _LobbyManager extends WavedashManager {
   handleLobbyKicked(reason = LobbyKickedReason.KICKED) {
     const lobbyId = this.lobbyId;
     if (!lobbyId) return;
-    logger.warn(
-      `User was removed from lobby: ${lobbyId} (reason: ${reason})`
-    );
+    logger.warn(`User was removed from lobby: ${lobbyId} (reason: ${reason})`);
     this.cleanupLobbyState();
     this.sdk.iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE.LOBBY_LEFT, {
       lobbyId
@@ -576,9 +570,7 @@ var _LobbyManager = class _LobbyManager extends WavedashManager {
     try {
       if (newUsers.length <= 1) {
         this.sdk.p2pManager.disconnectP2P();
-        logger.debug(
-          "Only one user in lobby, P2P connections disconnected"
-        );
+        logger.debug("Only one user in lobby, P2P connections disconnected");
         return;
       }
       const wavedashUsers = newUsers.map((lobbyUser) => ({
@@ -745,21 +737,41 @@ var FileSystemManager = class extends WavedashManager {
     return filePath;
   }
   /**
-   * Downloads a remote file to a local location
+   * Downloads a remote file to a local location.
+   * Throws on failure; the error message is the server's HTTP status (e.g. "404 (Not Found)")
+   * or a network-level description if the server didn't respond. See also: {@link remoteFileExists}
    * @param filePath - The path of the remote file to download
    * @returns The path of the local file that the remote file was downloaded to
    */
   async downloadRemoteFile(filePath) {
     const url = this.getRemoteStorageUrl(filePath);
-    const success = await this.download(url, filePath);
-    if (!success) {
-      throw new Error(`Failed to download file: ${filePath}`);
-    }
+    await this.download(url, filePath);
     return filePath;
   }
   /**
-   * Lists each file in a remote directory, including its subdirectories
-   * Returns only file paths, no directory paths
+   * Checks whether a remote file exists by issuing a HEAD request.
+   * Does NOT throw for the "file does not exist" case — returns false.
+   * Throws only for real errors (network failure, auth failure, server error).
+   * @param filePath - The path of the remote file to check
+   * @returns true if the remote file exists, false otherwise
+   */
+  async remoteFileExists(filePath) {
+    const url = this.getRemoteStorageUrl(filePath);
+    const jwt = await this.sdk.ensureGameplayJwt();
+    const response = await fetch(url, {
+      method: "HEAD",
+      headers: {
+        Authorization: `Bearer ${jwt}`
+      }
+    });
+    if (response.status === 404) return false;
+    if (response.ok) return true;
+    throw new Error(`${response.status} (${response.statusText})`);
+  }
+  /**
+   * Lists each file in a remote directory, including its subdirectories.
+   * Returns only file paths, no directory paths.
+   * An empty or non-existent directory returns an empty array — not an error.
    * @param path - The path of the remote directory to list
    * @returns A list of metadata for each file in the remote directory
    */
@@ -772,6 +784,7 @@ var FileSystemManager = class extends WavedashManager {
         Authorization: `Bearer ${jwt}`
       }
     });
+    if (response.status === 404) return [];
     if (!response.ok) {
       throw new Error(`${response.status} (${response.statusText})`);
     }
@@ -785,8 +798,14 @@ var FileSystemManager = class extends WavedashManager {
     const files = await this.listRemoteDirectory(path);
     const downloadPromises = files.map(async (file) => {
       const url = this.getRemoteStorageUrl(file.key);
-      const success = await this.download(url, file.key);
-      return { fileName: file.name, success };
+      try {
+        await this.download(url, file.key);
+        return { fileName: file.name, success: true };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to download ${file.name}: ${message}`);
+        return { fileName: file.name, success: false };
+      }
     });
     const downloadResults = await Promise.all(downloadPromises);
     const failedDownloads = downloadResults.filter((result) => !result.success);
@@ -849,12 +868,15 @@ var FileSystemManager = class extends WavedashManager {
     }
     return success;
   }
-  // Helper to download a file from a URL and save locally
+  // Helper to download a file from a URL and save locally.
+  // Throws on any failure with a message containing the HTTP status (e.g.
+  // "404 (Not Found)") for server-side failures, or a network/FS error
+  // description otherwise. Callers should let the error propagate; the
+  // public apiCall wrapper surfaces the message in WavedashResponse.message.
   async download(url, filePath) {
     logger.debug(`Downloading ${filePath} from: ${url}`);
     if (this.sdk.engineInstance && !this.sdk.engineInstance.FS) {
-      logger.error("Engine instance is missing the Emscripten FS API");
-      return false;
+      throw new Error("Engine instance is missing the Emscripten FS API");
     }
     const jwt = await this.sdk.ensureGameplayJwt();
     const response = await fetch(url, {
@@ -864,36 +886,34 @@ var FileSystemManager = class extends WavedashManager {
       }
     });
     if (!response.ok) {
-      logger.error(
-        `Failed to download remote file: ${response.status} (${response.statusText})`
-      );
-      return false;
+      throw new Error(`${response.status} (${response.statusText})`);
     }
     const blob = await response.blob();
     const arrayBuffer = await blob.arrayBuffer();
     const dataArray = new Uint8Array(arrayBuffer);
-    try {
-      if (this.sdk.engineInstance) {
-        const dirPath = filePath.substring(0, filePath.lastIndexOf("/"));
-        if (dirPath) {
-          try {
-            this.sdk.engineInstance.FS.mkdirTree(dirPath);
-          } catch (_error) {
-          }
+    if (this.sdk.engineInstance) {
+      const dirPath = filePath.substring(0, filePath.lastIndexOf("/"));
+      if (dirPath) {
+        try {
+          this.sdk.engineInstance.FS.mkdirTree(dirPath);
+        } catch (_error) {
         }
+      }
+      try {
         this.sdk.engineInstance.FS.writeFile(filePath, dataArray);
-      } else {
-        const success = await this.writeLocalFile(filePath, dataArray);
-        if (!success) return false;
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to save file ${filePath} to engine FS: ${msg}`);
+      }
+    } else {
+      const success = await this.writeLocalFile(filePath, dataArray);
+      if (!success) {
+        throw new Error(
+          `Failed to save file ${filePath} to local IndexedDB storage`
+        );
       }
-      logger.debug(`Successfully saved to: ${filePath}`);
-      return true;
-    } catch (error) {
-      logger.error(
-        `Failed to save file ${filePath}: ${error instanceof Error ? error.message : String(error)}`
-      );
-      return false;
     }
+    logger.debug(`Successfully saved to: ${filePath}`);
   }
   // ================
   // Private Methods
@@ -1051,12 +1071,11 @@ var UGCManager = class extends WavedashManager {
       api3.sdk.userGeneratedContent.getUGCItemDownloadUrl,
       { ugcId }
     );
-    const success = await this.sdk.fileSystemManager.download(
-      downloadUrl,
-      filePath
-    );
-    if (!success) {
-      throw new Error(`Failed to download UGC item: ${ugcId}`);
+    try {
+      await this.sdk.fileSystemManager.download(downloadUrl, filePath);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to download UGC item ${ugcId}: ${msg}`);
     }
     return ugcId;
   }
@@ -1303,9 +1322,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
       return this.updateP2PConnection(members);
     }
     if (this.initializationInProgress && this.initializationLobbyId === lobbyId) {
-      logger.debug(
-        "P2P initialization already in progress, waiting..."
-      );
+      logger.debug("P2P initialization already in progress, waiting...");
       await this.initializationInProgress;
       if (this.currentConnection) {
         return this.updateP2PConnection(members);
@@ -1386,9 +1403,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
           existingPeer.username = member.username;
         }
       } else {
-        logger.debug(
-          `Adding new peer: ${member.username} (${member.id})`
-        );
+        logger.debug(`Adding new peer: ${member.username} (${member.id})`);
         this.currentConnection.peers[member.id] = {
           userId: member.id,
           username: member.username
@@ -1421,9 +1436,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
           return this.createOfferToPeer(userId);
         });
         await Promise.all(offerPromises);
-        logger.debug(
-          `Initiated ${offerPromises.length} offers to new peers`
-        );
+        logger.debug(`Initiated ${offerPromises.length} offers to new peers`);
       }
     }
     for (const userId of Object.keys(
@@ -1512,10 +1525,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
           this.pendingProcessedMessageIds.delete(messageId);
         }
       } catch (error) {
-        logger.error(
-          "Failed to mark signaling messages as processed:",
-          error
-        );
+        logger.error("Failed to mark signaling messages as processed:", error);
         for (const messageId of newMessageIds) {
           this.pendingProcessedMessageIds.delete(messageId);
         }
@@ -1569,9 +1579,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
         await this.flushPendingIceCandidates(remoteUserId, pc);
         const answer = await pc.createAnswer();
         await pc.setLocalDescription(answer);
-        logger.debug(
-          `  Answer created, waiting for ondatachannel events...`
-        );
+        logger.debug(`  Answer created, waiting for ondatachannel events...`);
         const answerData = {
           type: answer.type,
           sdp: answer.sdp
@@ -1603,10 +1611,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
         break;
       }
       default:
-        logger.warn(
-          "Unknown signaling message type:",
-          message.messageType
-        );
+        logger.warn("Unknown signaling message type:", message.messageType);
     }
   }
   /**
@@ -1648,9 +1653,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
     const peersToInitiate = Object.keys(connection.peers).filter((userId) => currentUserId < userId);
     if (peersToInitiate.length > 0) {
       const offerPromises = peersToInitiate.map((userId) => {
-        logger.debug(
-          `Initiating offer to peer ${userId} (lower userId rule)`
-        );
+        logger.debug(`Initiating offer to peer ${userId} (lower userId rule)`);
         return this.createOfferToPeer(userId);
       });
       await Promise.all(offerPromises);
@@ -1691,9 +1694,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
   async createPeerConnection(remoteUserId, connection, shouldCreateChannels = false) {
     const iceServers = await this.getIceServers();
     if (!iceServers) {
-      logger.error(
-        `No ICE servers available for peer ${remoteUserId}`
-      );
+      logger.error(`No ICE servers available for peer ${remoteUserId}`);
       this.sdk.gameEventManager.notifyGame(
         WavedashEvents.P2P_CONNECTION_FAILED,
         {
@@ -1919,9 +1920,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
   }
   setupDataChannelHandlers(channel, remoteUserId, type) {
     channel.onopen = () => {
-      logger.debug(
-        `${type} data channel opened with peer ${remoteUserId}`
-      );
+      logger.debug(`${type} data channel opened with peer ${remoteUserId}`);
       if (this.isPeerReady(remoteUserId) && !this.establishedPeers.has(remoteUserId)) {
         this.establishedPeers.add(remoteUserId);
         const peer = this.currentConnection?.peers[remoteUserId];
@@ -1940,10 +1939,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
       this.enqueueMessage(event.data, remoteUserId);
     };
     channel.onerror = (error) => {
-      logger.error(
-        `Data channel error with peer ${remoteUserId}:`,
-        error
-      );
+      logger.error(`Data channel error with peer ${remoteUserId}:`, error);
       const peer = this.currentConnection?.peers[remoteUserId];
       if (peer) {
         this.sdk.gameEventManager.notifyGame(
@@ -1957,9 +1953,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
       }
     };
     channel.onclose = () => {
-      logger.debug(
-        `${type} data channel closed with peer ${remoteUserId}`
-      );
+      logger.debug(`${type} data channel closed with peer ${remoteUserId}`);
       this.establishedPeers.delete(remoteUserId);
       this.reconnectingPeers.delete(remoteUserId);
       const peer = this.currentConnection?.peers[remoteUserId];
@@ -1988,9 +1982,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
         return false;
       }
       if (!payload) {
-        logger.error(
-          `P2P send called with missing payload, dropping message.`
-        );
+        logger.error(`P2P send called with missing payload, dropping message.`);
         this.reportPacketDrop(appChannel, "SEND", "INVALID_PAYLOAD_SIZE");
         return false;
       }
@@ -2031,10 +2023,7 @@ var _P2PManager = class _P2PManager extends WavedashManager {
           try {
             channel.send(messageData);
           } catch (error) {
-            logger.error(
-              `P2P broadcast to peer ${peerUserId} failed:`,
-              error
-            );
+            logger.error(`P2P broadcast to peer ${peerUserId} failed:`, error);
           }
         });
       } else {
@@ -2517,11 +2506,10 @@ var StatsManager = class extends WavedashManager {
     // storeNow=true (and storeStats()) call .flush() to fire the pending invocation
     // immediately. The in-flight gate in persist() covers mutations that outlast
     // the throttle window, which would otherwise overlap and cause OCC conflicts.
-    this.throttledPersist = throttle2(
-      () => this.persist(),
-      STORE_THROTTLE_MS,
-      { leading: false, trailing: true }
-    );
+    this.throttledPersist = throttle2(() => this.persist(), STORE_THROTTLE_MS, {
+      leading: false,
+      trailing: true
+    });
     this.subscribe();
     this.requestStats().catch((error) => {
       logger.error("Initial stats fetch failed:", error);
@@ -2557,10 +2545,7 @@ var StatsManager = class extends WavedashManager {
           this.knownAchievementIds = new Set(ids);
         },
         (error) => {
-          logger.error(
-            "Achievement identifiers subscription error:",
-            error
-          );
+          logger.error("Achievement identifiers subscription error:", error);
         }
       ),
       this.sdk.convexClient.onUpdate(
@@ -2834,9 +2819,7 @@ var HeartbeatManager = class extends WavedashManager {
         );
       } else if (!this.isConnected && wasConnected) {
         this.disconnectedAt = Date.now();
-        logger.warn(
-          "Backend disconnected - attempting to reconnect..."
-        );
+        logger.warn("Backend disconnected - attempting to reconnect...");
         this.sdk.gameEventManager.notifyGame(
           WavedashEvents.BACKEND_RECONNECTING,
           connection
@@ -3118,7 +3101,7 @@ var FriendsManager = class extends WavedashManager {
   /**
    * Replace the leaderboard-page cache with the users from a single page of
    * leaderboard entries.
-   * 
+   *
    * In general devs should just use the username and userAvatarUrl returned
    * from `listLeaderboardEntries` directly, but we cache the latest leaderboard
    * page here just so getUserAvatarUrl and getUsername still work for the current page.
@@ -3515,9 +3498,7 @@ var WavedashSDK = class extends EventTarget {
     }
     this.config = config ?? {};
     this._initialized = true;
-    logger.setLogLevel(
-      this.config.debug ? LOG_LEVEL.DEBUG : LOG_LEVEL.WARN
-    );
+    logger.setLogLevel(this.config.debug ? LOG_LEVEL.DEBUG : LOG_LEVEL.WARN);
     this.p2pManager.init(this.config.p2p);
     logger.debug("Initialized with config:", this.config);
     if (!this.config.deferEvents) {
@@ -3903,9 +3884,10 @@ var WavedashSDK = class extends EventTarget {
     );
   }
   /**
-   * Downloads a remote file to a local location
+   * Downloads a remote file to a local location.
+   * Returns success=false (with the server status in `message`) if the file
+   * doesn't exist or any other error occurs. See also: {@link remoteFileExists}
    * @param filePath - The path of the remote file to download
-   * @param downloadTo - Optionally provide a path to download the file to, defaults to the same path as the remote file
    * @returns The path of the local file that the remote file was downloaded to
    */
   async downloadRemoteFile(filePath) {
@@ -3916,6 +3898,19 @@ var WavedashSDK = class extends EventTarget {
       filePath
     );
   }
+  /**
+   * Checks whether a remote file exists. Sends a lightweight HEAD request to check for existence.
+   * @param filePath - The path of the remote file to check
+   * @returns true if the remote file exists, false if it does not.
+   */
+  async remoteFileExists(filePath) {
+    return this.apiCall(
+      this.fileSystemManager,
+      "remoteFileExists",
+      [["filePath", vString]],
+      filePath
+    );
+  }
   /**
    * Uploads a local file to remote storage
    * @param filePath - The path of the local file to upload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wvdsh/sdk-js",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "type": "module",
   "description": "Wavedash JavaScript SDK",
   "main": "./dist/client.js",