@wvdsh/sdk-js 1.3.10 → 1.3.12

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { WavedashSDK } from './index.js';
-export { BackendConnectionPayload, EngineInstance, Friend, FullscreenChangedPayload, Leaderboard, LeaderboardDisplayType, LeaderboardEntries, LeaderboardSortOrder, Lobby, LobbyDataUpdatedPayload, LobbyInvite, LobbyInvitePayload, LobbyJoinResponse, LobbyJoinedPayload, LobbyKickedPayload, LobbyKickedReason, LobbyMessage, LobbyMessagePayload, LobbyUser, LobbyUserChangeType, LobbyUsersUpdatedPayload, LobbyVisibility, P2PConfig, P2PConnection, P2PConnectionEstablishedPayload, P2PConnectionFailedPayload, P2PMessage, P2PPacketDropReason, P2PPacketDroppedPayload, P2PPeer, P2PPeerDisconnectedPayload, P2PPeerReconnectedPayload, P2PPeerReconnectingPayload, RemoteFileMetadata, StatsStoredPayload, UGCType, UGCVisibility, UpsertedLeaderboardEntry, WavedashConfig, WavedashEvent, WavedashEventMap, WavedashResponse } from './index.js';
+export { BackendConnectionPayload, EngineInstance, Friend, FullscreenChangedPayload, Leaderboard, LeaderboardDisplayType, LeaderboardEntries, LeaderboardSortOrder, ListUGCItemsArgs, Lobby, LobbyDataUpdatedPayload, LobbyInvite, LobbyInvitePayload, LobbyJoinResponse, LobbyJoinedPayload, LobbyKickedPayload, LobbyKickedReason, LobbyMessage, LobbyMessagePayload, LobbyUser, LobbyUserChangeType, LobbyUsersUpdatedPayload, LobbyVisibility, P2PConfig, P2PConnection, P2PConnectionEstablishedPayload, P2PConnectionFailedPayload, P2PMessage, P2PPacketDropReason, P2PPacketDroppedPayload, P2PPeer, P2PPeerDisconnectedPayload, P2PPeerReconnectedPayload, P2PPeerReconnectingPayload, PaginatedUGCItems, RemoteFileMetadata, StatsStoredPayload, UGCItem, UGCType, UGCVisibility, UpdateUGCItemArgs, UpsertedLeaderboardEntry, WavedashConfig, WavedashEvent, WavedashEventMap, WavedashResponse } from './index.js';
 export { GameLaunchParams } from '@wvdsh/api';
 export { GenericId as Id } from 'convex/values';
 import 'convex/browser';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ConvexClient } from 'convex/browser';
 import { GenericId } from 'convex/values';
 export { GenericId as Id } from 'convex/values';
-import { FunctionReturnType } from 'convex/server';
+import { FunctionReturnType, FunctionArgs } from 'convex/server';
 import { LOBBY_VISIBILITY, api, UGC_TYPE, UGC_VISIBILITY, LEADERBOARD_SORT_ORDER, LEADERBOARD_DISPLAY_TYPE, GAME_ENGINE, SDKUser, IFrameEventPayloadMap, IFRAME_MESSAGE_TYPE, SDKConfig, GameLaunchParams } from '@wvdsh/api';
 export { GameLaunchParams } from '@wvdsh/api';
 
@@ -71,6 +71,13 @@ type LeaderboardSortOrder = (typeof LEADERBOARD_SORT_ORDER)[keyof typeof LEADERB
 type LeaderboardDisplayType = (typeof LEADERBOARD_DISPLAY_TYPE)[keyof typeof LEADERBOARD_DISPLAY_TYPE];
 type UGCType = (typeof UGC_TYPE)[keyof typeof UGC_TYPE];
 type UGCVisibility = (typeof UGC_VISIBILITY)[keyof typeof UGC_VISIBILITY];
+type UpdateUGCItemArgs = Omit<FunctionArgs<typeof api.sdk.userGeneratedContent.updateUGCItem>, "ugcId" | "createPresignedUploadUrl"> & {
+    filePath?: string;
+};
+type UGCItem = FunctionReturnType<typeof api.sdk.userGeneratedContent.listUGCItems>["page"][0];
+type PaginatedUGCItems = FunctionReturnType<typeof api.sdk.userGeneratedContent.listUGCItems>;
+type RawListUGCItemsArgs = FunctionArgs<typeof api.sdk.userGeneratedContent.listUGCItems>;
+type ListUGCItemsArgs = Omit<RawListUGCItemsArgs, "filters"> & NonNullable<RawListUGCItemsArgs["filters"]>;
 type LobbyUser = FunctionReturnType<typeof api.sdk.gameLobby.lobbyUsers>[0];
 type LobbyMessage = FunctionReturnType<typeof api.sdk.gameLobby.lobbyMessages>[0];
 type Lobby = FunctionReturnType<typeof api.sdk.gameLobby.listAvailable>[0];
@@ -385,14 +392,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 +419,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;
@@ -418,9 +436,10 @@ declare class FileSystemManager extends WavedashManager {
 declare class UGCManager extends WavedashManager {
     constructor(sdk: WavedashSDK);
     createUGCItem(ugcType: UGCType, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<GenericId<"userGeneratedContent">>;
-    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<GenericId<"userGeneratedContent">>;
+    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, updates?: UpdateUGCItemArgs): Promise<GenericId<"userGeneratedContent">>;
     deleteUGCItem(ugcId: GenericId<"userGeneratedContent">): Promise<GenericId<"userGeneratedContent">>;
     downloadUGCItem(ugcId: GenericId<"userGeneratedContent">, filePath: string): Promise<GenericId<"userGeneratedContent">>;
+    listUGCItems(args?: ListUGCItemsArgs): Promise<PaginatedUGCItems>;
 }
 
 /**
@@ -623,7 +642,7 @@ declare class HeartbeatManager extends WavedashManager {
      * @param data - Data to send to the backend
      * @returns true if the presence was updated successfully
      */
-    updateUserPresence(data?: Record<string, unknown>): Promise<boolean>;
+    updateUserPresence(data?: Record<string, string | number | boolean | null>): Promise<boolean>;
     /**
      * Tests the connection to the backend
      */
@@ -837,7 +856,6 @@ declare class WavedashSDK extends EventTarget {
     };
     UGCVisibility: {
         readonly PUBLIC: 0;
-        readonly FRIENDS_ONLY: 1;
         readonly PRIVATE: 2;
     };
     AvatarSize: {
@@ -987,21 +1005,19 @@ declare class WavedashSDK extends EventTarget {
     createUGCItem(ugcType: UGCType, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
     /**
      * Updates a UGC item and uploads the file to the server if a filePath is provided
-     * TODO: GD Script cannot call with optional arguments, convert this to accept a single dictionary of updates
-     * @param ugcId
-     * @param title
-     * @param description
-     * @param visibility
-     * @param filePath - optional IndexedDB key file path to upload to the server. If not provided, the UGC item will be updated but no file will be uploaded.
+     * @param ugcId - The ID of the UGC item to update
+     * @param updates - Object containing the fields to update. May also be passed
+     *   as a JSON string by engine bridges (Godot) that can't marshal a dict.
      * @returns ugcId
      */
-    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
+    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, updates?: UpdateUGCItemArgs): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
     /**
      * Delete a UGC item: removes the row, the R2 object, and frees up the
      * user's storage quota by the size of the deleted upload.
      */
     deleteUGCItem(ugcId: GenericId<"userGeneratedContent">): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
     downloadUGCItem(ugcId: GenericId<"userGeneratedContent">, filePath: string): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
+    listUGCItems(args?: ListUGCItemsArgs): Promise<WavedashResponse<PaginatedUGCItems>>;
     /**
      * Deletes a remote file from storage
      * @param filePath - The path of the remote file to delete
@@ -1009,12 +1025,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
@@ -1140,11 +1163,10 @@ declare class WavedashSDK extends EventTarget {
     getLobbyInviteLink(copyToClipboard?: boolean): Promise<WavedashResponse<string>>;
     /**
      * Updates rich user presence so friends can see what the player is doing in game
-     * TODO: data param should be more strongly typed
      * @param data Game data to send to the backend
      * @returns true if the presence was updated successfully
      */
-    updateUserPresence(data?: Record<string, unknown>): Promise<WavedashResponse<boolean>>;
+    updateUserPresence(data?: Record<string, string | number | boolean | null>): Promise<WavedashResponse<boolean>>;
     private isGodot;
     private formatResponse;
     private ensureInit;
@@ -1191,4 +1213,4 @@ declare global {
 
 declare function setupWavedashSDK(): WavedashSDK;
 
-export { type BackendConnectionPayload, type EngineInstance, type Friend, type FullscreenChangedPayload, type Leaderboard, type LeaderboardDisplayType, type LeaderboardEntries, type LeaderboardSortOrder, type Lobby, type LobbyDataUpdatedPayload, type LobbyInvite, type LobbyInvitePayload, type LobbyJoinResponse, type LobbyJoinedPayload, type LobbyKickedPayload, type LobbyKickedReason, type LobbyMessage, type LobbyMessagePayload, type LobbyUser, type LobbyUserChangeType, type LobbyUsersUpdatedPayload, type LobbyVisibility, type P2PConfig, type P2PConnection, type P2PConnectionEstablishedPayload, type P2PConnectionFailedPayload, type P2PMessage, type P2PPacketDropReason, type P2PPacketDroppedPayload, type P2PPeer, type P2PPeerDisconnectedPayload, type P2PPeerReconnectedPayload, type P2PPeerReconnectingPayload, type RemoteFileMetadata, type StatsStoredPayload, type UGCType, type UGCVisibility, type UpsertedLeaderboardEntry, type WavedashConfig, type WavedashEvent, type WavedashEventMap, type WavedashResponse, WavedashSDK, setupWavedashSDK };
+export { type BackendConnectionPayload, type EngineInstance, type Friend, type FullscreenChangedPayload, type Leaderboard, type LeaderboardDisplayType, type LeaderboardEntries, type LeaderboardSortOrder, type ListUGCItemsArgs, type Lobby, type LobbyDataUpdatedPayload, type LobbyInvite, type LobbyInvitePayload, type LobbyJoinResponse, type LobbyJoinedPayload, type LobbyKickedPayload, type LobbyKickedReason, type LobbyMessage, type LobbyMessagePayload, type LobbyUser, type LobbyUserChangeType, type LobbyUsersUpdatedPayload, type LobbyVisibility, type P2PConfig, type P2PConnection, type P2PConnectionEstablishedPayload, type P2PConnectionFailedPayload, type P2PMessage, type P2PPacketDropReason, type P2PPacketDroppedPayload, type P2PPeer, type P2PPeerDisconnectedPayload, type P2PPeerReconnectedPayload, type P2PPeerReconnectingPayload, type PaginatedUGCItems, type RemoteFileMetadata, type StatsStoredPayload, type UGCItem, type UGCType, type UGCVisibility, type UpdateUGCItemArgs, type UpsertedLeaderboardEntry, type WavedashConfig, type WavedashEvent, type WavedashEventMap, type WavedashResponse, WavedashSDK, setupWavedashSDK };

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
@@ -1013,7 +1033,8 @@ var UGCManager = class extends WavedashManager {
     }
     return ugcId;
   }
-  async updateUGCItem(ugcId, title, description, visibility, filePath) {
+  async updateUGCItem(ugcId, updates = {}) {
+    const { title, description, visibility, filePath } = updates;
     const { uploadUrl } = await this.sdk.convexClient.mutation(
       api3.sdk.userGeneratedContent.updateUGCItem,
       {
@@ -1051,15 +1072,26 @@ 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;
   }
+  async listUGCItems(args = {}) {
+    const { createdBy, ugcType, titleSearch, numItems, continueCursor } = args;
+    const filters = createdBy !== void 0 || ugcType !== void 0 || titleSearch !== void 0 ? { createdBy, ugcType, titleSearch } : void 0;
+    return await this.sdk.convexClient.query(
+      api3.sdk.userGeneratedContent.listUGCItems,
+      {
+        filters,
+        numItems,
+        continueCursor
+      }
+    );
+  }
 };
 
 // src/services/leaderboards.ts
@@ -1303,9 +1335,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 +1416,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 +1449,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 +1538,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 +1592,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 +1624,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 +1666,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 +1707,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 +1933,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 +1952,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 +1966,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 +1995,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 +2036,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 +2519,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 +2558,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 +2832,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 +3114,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.
@@ -3379,11 +3375,29 @@ function vUnion(...variants) {
     throw new Error(`${path}: no variant matched, got ${describeValue(value)}`);
   };
 }
+function vObject(shape) {
+  return (value, path) => {
+    const obj = vRecord(value, path);
+    for (const key of Object.keys(obj)) {
+      if (!(key in shape)) {
+        throw new Error(`${path}: unrecognized property "${key}"`);
+      }
+    }
+    for (const key of Object.keys(shape)) {
+      shape[key](obj[key], `${path}.${key}`);
+    }
+    return obj;
+  };
+}
 function validateArgs(methodName, specs, values) {
+  const shape = {};
+  const obj = {};
   for (let i = 0; i < specs.length; i++) {
     const [argName, validator] = specs[i];
-    validator(values[i], `${methodName}.${argName}`);
+    shape[argName] = validator;
+    obj[argName] = values[i];
   }
+  vObject(shape)(obj, methodName);
 }
 function describeValue(value) {
   if (value === void 0) return "undefined";
@@ -3515,9 +3529,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) {
@@ -3836,30 +3848,45 @@ var WavedashSDK = class extends EventTarget {
   }
   /**
    * Updates a UGC item and uploads the file to the server if a filePath is provided
-   * TODO: GD Script cannot call with optional arguments, convert this to accept a single dictionary of updates
-   * @param ugcId
-   * @param title
-   * @param description
-   * @param visibility
-   * @param filePath - optional IndexedDB key file path to upload to the server. If not provided, the UGC item will be updated but no file will be uploaded.
+   * @param ugcId - The ID of the UGC item to update
+   * @param updates - Object containing the fields to update. May also be passed
+   *   as a JSON string by engine bridges (Godot) that can't marshal a dict.
    * @returns ugcId
    */
-  async updateUGCItem(ugcId, title, description, visibility, filePath) {
+  async updateUGCItem(ugcId, updates = {}) {
+    if (typeof updates === "string") {
+      const raw = updates;
+      try {
+        updates = JSON.parse(raw);
+      } catch (error) {
+        const message = `updateUGCItem: invalid JSON: ${raw}`;
+        logger.error(message, error);
+        return this.formatResponse({
+          success: false,
+          data: null,
+          message
+        });
+      }
+    }
     return this.apiCall(
       this.ugcManager,
       "updateUGCItem",
       [
         ["ugcId", vId("userGeneratedContent")],
-        ["title", vOptional(vString)],
-        ["description", vOptional(vString)],
-        ["visibility", vOptional(vEnum(UGC_VISIBILITY, "UGCVisibility"))],
-        ["filePath", vOptional(vString)]
+        [
+          "updates",
+          vOptional(
+            vObject({
+              title: vOptional(vString),
+              description: vOptional(vString),
+              visibility: vOptional(vEnum(UGC_VISIBILITY, "UGCVisibility")),
+              filePath: vOptional(vString)
+            })
+          )
+        ]
       ],
       ugcId,
-      title,
-      description,
-      visibility,
-      filePath
+      updates
     );
   }
   /**
@@ -3886,6 +3913,47 @@ var WavedashSDK = class extends EventTarget {
       filePath
     );
   }
+  async listUGCItems(args = {}) {
+    if (typeof args === "string") {
+      const raw = args;
+      try {
+        args = JSON.parse(raw);
+      } catch (error) {
+        const message = `listUGCItems: invalid JSON: ${raw}`;
+        logger.error(message, error);
+        return this.formatResponse({
+          success: false,
+          data: null,
+          message
+        });
+      }
+    }
+    return this.apiCall(
+      this.ugcManager,
+      "listUGCItems",
+      [
+        [
+          "args",
+          vOptional((value, path) => {
+            const obj = vObject({
+              createdBy: vOptional(vId("users")),
+              ugcType: vOptional(vEnum(UGC_TYPE, "UGCType")),
+              titleSearch: vOptional(vString),
+              numItems: vOptional(vNumber),
+              continueCursor: vOptional(vString)
+            })(value, path);
+            if (obj.continueCursor !== void 0 && (obj.createdBy !== void 0 || obj.ugcType !== void 0 || obj.titleSearch !== void 0 || obj.numItems !== void 0)) {
+              throw new Error(
+                `${path}: continueCursor should be the only argument if present`
+              );
+            }
+            return obj;
+          })
+        ]
+      ],
+      args
+    );
+  }
   // ================================
   // Save state / Remote File Storage
   // ================================
@@ -3903,9 +3971,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 +3985,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
@@ -4287,7 +4369,6 @@ var WavedashSDK = class extends EventTarget {
   // ==============================
   /**
    * Updates rich user presence so friends can see what the player is doing in game
-   * TODO: data param should be more strongly typed
    * @param data Game data to send to the backend
    * @returns true if the presence was updated successfully
    */

package/package.json

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