@wvdsh/sdk-js 1.2.3 → 1.3.0

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+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 { GameLaunchParams } from '@wvdsh/api';
+export { GenericId as Id } from 'convex/values';
+import 'convex/browser';
+import 'convex/server';
+
+declare global {
+    interface Window {
+        Wavedash: WavedashSDK;
+    }
+}
+declare const Wavedash: WavedashSDK;
+
+export { WavedashSDK, Wavedash as default };

package/dist/client.js

@@ -0,0 +1,11 @@
+// src/client.ts
+var Wavedash = window.Wavedash;
+if (!Wavedash) {
+  throw new Error(
+    "Wavedash is not initialized. If you're running your game locally use the `wavedash dev` command to ensure the Wavedash SDK is loaded."
+  );
+}
+var client_default = Wavedash;
+export {
+  client_default as default
+};

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { ConvexClient } from 'convex/browser';
 import { GenericId } from 'convex/values';
 export { GenericId as Id } from 'convex/values';
 import { FunctionReturnType } from 'convex/server';
-import { PublicApiType, api, GAME_ENGINE, SDKUser, IFrameEventPayloadMap, IFRAME_MESSAGE_TYPE, SDKConfig, GameLaunchParams } from '@wvdsh/api';
+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';
 
 /**
@@ -33,29 +33,57 @@ declare const WavedashEvents: {
     readonly FULLSCREEN_CHANGED: "FullscreenChanged";
 };
 
-type LobbyVisibility = PublicApiType["sdk"]["gameLobby"]["createAndJoinLobby"]["_args"]["visibility"];
+/** Reasons why a user was kicked from a lobby */
+declare const LobbyKickedReason$1: {
+    readonly KICKED: "KICKED";
+    readonly ERROR: "ERROR";
+};
+/** Change types for lobby user updates */
+declare const LobbyUserChangeType$1: {
+    readonly JOINED: "JOINED";
+    readonly LEFT: "LEFT";
+};
+/**
+ * Reason a P2P packet was dropped. Each reason implies a different
+ * game-side remedy:
+ * - QUEUE_FULL: throttle your sends, bundle updates into fewer packets, or increase p2p maxIncomingMessages config
+ * - PAYLOAD_TOO_LARGE: reduce payload or increase p2p messageSize config
+ * - INVALID_PAYLOAD_SIZE: programming error
+ * - INVALID_CHANNEL: SDK version skew or malicious peer
+ * - MALFORMED: wire data too short to parse; channel will be -1
+ * - PEER_NOT_READY: P2P not yet initialized, or peer was never ready / closed mid-send. If P2P hasn't been initialized, initialize it first; otherwise wait for P2P_CONNECTION_ESTABLISHED and watch P2P_PEER_DISCONNECTED/P2P_CONNECTION_FAILED/P2P_PEER_RECONNECTING for reachability.
+ */
+declare const P2PPacketDropReason$1: {
+    readonly QUEUE_FULL: "QUEUE_FULL";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly INVALID_PAYLOAD_SIZE: "INVALID_PAYLOAD_SIZE";
+    readonly INVALID_CHANNEL: "INVALID_CHANNEL";
+    readonly MALFORMED: "MALFORMED";
+    readonly PEER_NOT_READY: "PEER_NOT_READY";
+};
+
+/**
+ * Public types exported from @wvdsh/sdk-js
+ */
+
+type LobbyVisibility = (typeof LOBBY_VISIBILITY)[keyof typeof LOBBY_VISIBILITY];
+type LeaderboardSortOrder = (typeof LEADERBOARD_SORT_ORDER)[keyof typeof LEADERBOARD_SORT_ORDER];
+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 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];
 type LobbyJoinResponse = FunctionReturnType<typeof api.sdk.gameLobby.joinLobby>;
 type LobbyInvite = FunctionReturnType<typeof api.sdk.gameLobby.getLobbyInvites>[0];
 type Friend = FunctionReturnType<typeof api.sdk.friends.listFriends>[0];
-type UGCType = PublicApiType["sdk"]["userGeneratedContent"]["createUGCItem"]["_args"]["ugcType"];
-type UGCVisibility = PublicApiType["sdk"]["userGeneratedContent"]["createUGCItem"]["_args"]["visibility"];
-type LeaderboardSortOrder = PublicApiType["sdk"]["leaderboards"]["getOrCreateLeaderboard"]["_args"]["sortOrder"];
-type LeaderboardDisplayType = PublicApiType["sdk"]["leaderboards"]["getOrCreateLeaderboard"]["_args"]["displayType"];
 type Leaderboard = FunctionReturnType<typeof api.sdk.leaderboards.getLeaderboard>;
 type LeaderboardEntries = FunctionReturnType<typeof api.sdk.leaderboards.listEntriesAroundUser>["entries"];
 type UpsertedLeaderboardEntry = FunctionReturnType<typeof api.sdk.leaderboards.upsertLeaderboardEntry>["entry"] & {
     userId: GenericId<"users">;
     username: string;
 };
-type P2PTurnCredentials = FunctionReturnType<typeof api.sdk.turnCredentials.getOrCreate>;
-type P2PSignalingMessage = Omit<FunctionReturnType<typeof api.sdk.p2pSignaling.getSignalingMessages>[0], "data"> & {
-    data: RTCSessionDescriptionInit | RTCIceCandidateInit;
-};
 type WavedashEvent = (typeof WavedashEvents)[keyof typeof WavedashEvents];
-
 interface WavedashConfig {
     debug?: boolean;
     remoteStorageOrigin?: string;
@@ -73,7 +101,7 @@ interface RemoteFileMetadata {
 }
 interface EngineInstance {
     type: (typeof GAME_ENGINE)[keyof typeof GAME_ENGINE];
-    SendMessage(objectName: string, methodName: WavedashEvent, value?: string | number | boolean): void;
+    SendMessage(objectName: string, methodName: WavedashEvent, value?: string | number): void;
     FS: {
         readFile(path: string, opts?: Record<string, unknown>): string | Uint8Array;
         writeFile(path: string, data: string | ArrayBufferView, opts?: Record<string, unknown>): void;
@@ -85,11 +113,14 @@ interface EngineInstance {
     };
     unityPersistentDataPath?: string;
 }
-interface WavedashResponse<T> {
-    success: boolean;
-    data: T | null;
-    message?: string;
-}
+type WavedashResponse<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    data: null;
+    message: string;
+};
 /** Payload for LobbyJoined event - emitted on successful lobby join or create */
 interface LobbyJoinedPayload {
     lobbyId: GenericId<"lobbies">;
@@ -97,23 +128,13 @@ interface LobbyJoinedPayload {
     users: LobbyUser[];
     metadata: Record<string, unknown>;
 }
-/** Reasons why a user was kicked from a lobby */
-declare const LobbyKickedReason: {
-    readonly KICKED: "KICKED";
-    readonly ERROR: "ERROR";
-};
-type LobbyKickedReason = (typeof LobbyKickedReason)[keyof typeof LobbyKickedReason];
+type LobbyKickedReason = (typeof LobbyKickedReason$1)[keyof typeof LobbyKickedReason$1];
 /** Payload for LobbyKicked event - emitted when removed from a lobby */
 interface LobbyKickedPayload {
     lobbyId: GenericId<"lobbies">;
     reason: LobbyKickedReason;
 }
-/** Change types for lobby user updates */
-declare const LobbyUserChangeType: {
-    readonly JOINED: "JOINED";
-    readonly LEFT: "LEFT";
-};
-type LobbyUserChangeType = (typeof LobbyUserChangeType)[keyof typeof LobbyUserChangeType];
+type LobbyUserChangeType = (typeof LobbyUserChangeType$1)[keyof typeof LobbyUserChangeType$1];
 /** Payload for LobbyUsersUpdated event - emitted when a user joins or leaves */
 interface LobbyUsersUpdatedPayload extends LobbyUser {
     changeType: LobbyUserChangeType;
@@ -155,11 +176,7 @@ interface P2PPeerReconnectedPayload {
     userId: GenericId<"users">;
     username: string;
 }
-/**
- * Reason a P2P packet was dropped. Each reason implies a different
- * game-side remedy.
- */
-type P2PPacketDropReason = "QUEUE_FULL" | "PAYLOAD_TOO_LARGE" | "INVALID_PAYLOAD_SIZE" | "INVALID_CHANNEL" | "MALFORMED" | "PEER_NOT_READY";
+type P2PPacketDropReason = (typeof P2PPacketDropReason$1)[keyof typeof P2PPacketDropReason$1];
 /**
  * Payload for P2PPacketDropped event.
  *
@@ -185,6 +202,29 @@ interface BackendConnectionPayload {
     connectionCount: number;
     connectionRetries: number;
 }
+/** Payload for FullscreenChanged event - emitted when fullscreen state flips */
+interface FullscreenChangedPayload {
+    isFullscreen: boolean;
+}
+type WavedashEventMap = {
+    [WavedashEvents.LOBBY_MESSAGE]: LobbyMessagePayload;
+    [WavedashEvents.LOBBY_JOINED]: LobbyJoinedPayload;
+    [WavedashEvents.LOBBY_KICKED]: LobbyKickedPayload;
+    [WavedashEvents.LOBBY_USERS_UPDATED]: LobbyUsersUpdatedPayload;
+    [WavedashEvents.LOBBY_DATA_UPDATED]: LobbyDataUpdatedPayload;
+    [WavedashEvents.LOBBY_INVITE]: LobbyInvitePayload;
+    [WavedashEvents.P2P_CONNECTION_ESTABLISHED]: P2PConnectionEstablishedPayload;
+    [WavedashEvents.P2P_CONNECTION_FAILED]: P2PConnectionFailedPayload;
+    [WavedashEvents.P2P_PEER_DISCONNECTED]: P2PPeerDisconnectedPayload;
+    [WavedashEvents.P2P_PEER_RECONNECTING]: P2PPeerReconnectingPayload;
+    [WavedashEvents.P2P_PEER_RECONNECTED]: P2PPeerReconnectedPayload;
+    [WavedashEvents.P2P_PACKET_DROPPED]: P2PPacketDroppedPayload;
+    [WavedashEvents.STATS_STORED]: StatsStoredPayload;
+    [WavedashEvents.BACKEND_CONNECTED]: BackendConnectionPayload;
+    [WavedashEvents.BACKEND_DISCONNECTED]: BackendConnectionPayload;
+    [WavedashEvents.BACKEND_RECONNECTING]: BackendConnectionPayload;
+    [WavedashEvents.FULLSCREEN_CHANGED]: FullscreenChangedPayload;
+};
 interface P2PPeer {
     userId: GenericId<"users">;
     username: string;
@@ -586,7 +626,7 @@ declare class GameEventManager {
     private sdk;
     private eventQueue;
     constructor(sdk: WavedashSDK);
-    notifyGame(event: WavedashEvent, payload: string | number | boolean | object): void;
+    notifyGame(event: WavedashEvent, payload: string | number | object): void;
     private sendGameEvent;
     flushEventQueue(): void;
 }
@@ -654,9 +694,6 @@ declare class OverlayManager {
  * Implements friend-related methods for the Wavedash SDK
  */
 
-declare const AVATAR_SIZE_SMALL = 0;
-declare const AVATAR_SIZE_MEDIUM = 1;
-declare const AVATAR_SIZE_LARGE = 2;
 declare class FriendsManager {
     private sdk;
     private userCache;
@@ -673,9 +710,10 @@ declare class FriendsManager {
         userAvatarUrl?: string;
     }>): void;
     /**
-     * Returns CDN URL with size transformation for a cached user's avatar
+     * Returns CDN URL with size transformation for a cached user's avatar.
      * @param userId - The user ID to get the avatar URL for
-     * @param size - Avatar size constant (AVATAR_SIZE_SMALL, AVATAR_SIZE_MEDIUM, or AVATAR_SIZE_LARGE)
+     * @param size - Pixel size for width and height. Use a value from
+     *   `AvatarSize` (SMALL=64, MEDIUM=128, LARGE=256) or any custom pixel size.
      * @returns CDN URL with size transformation, or null if user not cached or has no avatar
      */
     getUserAvatarUrl(userId: GenericId<"users">, size?: number): string | null;
@@ -764,6 +802,54 @@ declare class WavedashSDK extends EventTarget {
         readonly BACKEND_RECONNECTING: "BackendReconnecting";
         readonly FULLSCREEN_CHANGED: "FullscreenChanged";
     };
+    LobbyVisibility: {
+        readonly PUBLIC: 0;
+        readonly FRIENDS_ONLY: 1;
+        readonly PRIVATE: 2;
+    };
+    LeaderboardSortOrder: {
+        readonly ASC: 0;
+        readonly DESC: 1;
+    };
+    LeaderboardDisplayType: {
+        readonly NUMERIC: 0;
+        readonly TIME_SECONDS: 1;
+        readonly TIME_MILLISECONDS: 2;
+        readonly TIME_GAME_TICKS: 3;
+    };
+    UGCType: {
+        readonly SCREENSHOT: 0;
+        readonly VIDEO: 1;
+        readonly COMMUNITY: 2;
+        readonly GAME_MANAGED: 3;
+        readonly OTHER: 4;
+    };
+    UGCVisibility: {
+        readonly PUBLIC: 0;
+        readonly FRIENDS_ONLY: 1;
+        readonly PRIVATE: 2;
+    };
+    AvatarSize: {
+        readonly SMALL: 64;
+        readonly MEDIUM: 128;
+        readonly LARGE: 256;
+    };
+    LobbyKickedReason: {
+        readonly KICKED: "KICKED";
+        readonly ERROR: "ERROR";
+    };
+    LobbyUserChangeType: {
+        readonly JOINED: "JOINED";
+        readonly LEFT: "LEFT";
+    };
+    P2PPacketDropReason: {
+        readonly QUEUE_FULL: "QUEUE_FULL";
+        readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+        readonly INVALID_PAYLOAD_SIZE: "INVALID_PAYLOAD_SIZE";
+        readonly INVALID_CHANNEL: "INVALID_CHANNEL";
+        readonly MALFORMED: "MALFORMED";
+        readonly PEER_NOT_READY: "PEER_NOT_READY";
+    };
     protected lobbyManager: LobbyManager;
     protected statsManager: StatsManager;
     protected heartbeatManager: HeartbeatManager;
@@ -795,6 +881,25 @@ declare class WavedashSDK extends EventTarget {
      * If deferEvents is true, call this manually after your pre-game setup is complete.
      */
     readyForEvents(): void;
+    private listenerWrappers;
+    /**
+     * Subscribe to a Wavedash event with a payload-typed listener.
+     * Returns an unsubscribe function.
+     *
+     *   const unsubscribeLobbyJoined = Wavedash.on(Wavedash.Events.LOBBY_JOINED, (payload) => {
+     *     // payload: LobbyJoinedPayload
+     *   });
+     *   unsubscribeLobbyJoined(); // later
+     */
+    on<K extends keyof WavedashEventMap>(event: K, listener: (payload: WavedashEventMap[K]) => void): () => void;
+    /**
+     * Remove a listener previously registered with {@link on}.
+     */
+    off<K extends keyof WavedashEventMap>(event: K, listener: (payload: WavedashEventMap[K]) => void): void;
+    addEventListener<K extends keyof WavedashEventMap>(type: K, listener: (ev: CustomEvent<WavedashEventMap[K]>) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof WavedashEventMap>(type: K, listener: (ev: CustomEvent<WavedashEventMap[K]>) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
     loadScript(src: string): Promise<unknown>;
     updateLoadProgressZeroToOne(progress: number): void;
     loadComplete(): void;
@@ -845,7 +950,7 @@ declare class WavedashSDK extends EventTarget {
      * Get avatar URL for a cached user with size transformation.
      * Users are cached when seen via listFriends() or lobby membership.
      * @param userId - The user ID to get the avatar URL for
-     * @param size - Avatar size constant (AVATAR_SIZE_SMALL=0, AVATAR_SIZE_MEDIUM=1, AVATAR_SIZE_LARGE=2)
+     * @param size - Avatar size constant (Wavedash.AvatarSize.SMALL=0, Wavedash.AvatarSize.MEDIUM=1, Wavedash.AvatarSize.LARGE=2)
      * @returns CDN URL with size transformation, or null if user not cached or has no avatar
      */
     getUserAvatarUrl(userId: GenericId<"users">, size?: number): string | null;
@@ -1048,7 +1153,12 @@ declare class WavedashSDK extends EventTarget {
      */
     private setupSessionEndListeners;
 }
+declare global {
+    interface Window {
+        Wavedash: WavedashSDK;
+    }
+}
 
 declare function setupWavedashSDK(): WavedashSDK;
 
-export { AVATAR_SIZE_LARGE, AVATAR_SIZE_MEDIUM, AVATAR_SIZE_SMALL, type BackendConnectionPayload, type EngineInstance, type Friend, type Leaderboard, type LeaderboardDisplayType, type LeaderboardEntries, type LeaderboardSortOrder, type Lobby, type LobbyDataUpdatedPayload, type LobbyInvite, type LobbyInvitePayload, type LobbyJoinResponse, type LobbyJoinedPayload, type LobbyKickedPayload, LobbyKickedReason, type LobbyMessage, type LobbyMessagePayload, type LobbyUser, 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 P2PSignalingMessage, type P2PTurnCredentials, type RemoteFileMetadata, type StatsStoredPayload, type UGCType, type UGCVisibility, type UpsertedLeaderboardEntry, type WavedashConfig, type WavedashEvent, WavedashEvents, type WavedashResponse, WavedashSDK, setupWavedashSDK };
+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 };