@wvdsh/sdk-js 0.0.38 → 1.2.2

package/dist/index.d.ts

@@ -0,0 +1,972 @@
+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, IFRAME_MESSAGE_TYPE, IFrameEventPayloadMap, SDKConfig, GameLaunchParams } from '@wvdsh/api';
+export { GameLaunchParams } from '@wvdsh/api';
+
+/**
+ * SDK-to-Engine Events
+ *
+ * Defines all events that the SDK sends to the game engine.
+ * These are maintained manually in the SDK (not autogenerated from backend).
+ *
+ * The game engine listens for these events to react to SDK updates.
+ */
+declare const WavedashEvents: {
+    readonly LOBBY_MESSAGE: "LobbyMessage";
+    readonly LOBBY_JOINED: "LobbyJoined";
+    readonly LOBBY_KICKED: "LobbyKicked";
+    readonly LOBBY_USERS_UPDATED: "LobbyUsersUpdated";
+    readonly LOBBY_DATA_UPDATED: "LobbyDataUpdated";
+    readonly LOBBY_INVITE: "LobbyInvite";
+    readonly P2P_CONNECTION_ESTABLISHED: "P2PConnectionEstablished";
+    readonly P2P_CONNECTION_FAILED: "P2PConnectionFailed";
+    readonly P2P_PEER_DISCONNECTED: "P2PPeerDisconnected";
+    readonly P2P_PEER_RECONNECTING: "P2PPeerReconnecting";
+    readonly P2P_PEER_RECONNECTED: "P2PPeerReconnected";
+    readonly P2P_PACKET_DROPPED: "P2PPacketDropped";
+    readonly STATS_STORED: "StatsStored";
+    readonly BACKEND_CONNECTED: "BackendConnected";
+    readonly BACKEND_DISCONNECTED: "BackendDisconnected";
+    readonly BACKEND_RECONNECTING: "BackendReconnecting";
+};
+
+type LobbyVisibility = PublicApiType["sdk"]["gameLobby"]["createAndJoinLobby"]["_args"]["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;
+    p2p?: Partial<P2PConfig>;
+    deferEvents?: boolean;
+}
+
+interface RemoteFileMetadata {
+    exists: boolean;
+    key: string;
+    name: string;
+    lastModified: number;
+    size: number;
+    etag: string;
+}
+interface EngineInstance {
+    type: (typeof GAME_ENGINE)[keyof typeof GAME_ENGINE];
+    SendMessage(objectName: string, methodName: WavedashEvent, value?: string | number | boolean): void;
+    FS: {
+        readFile(path: string, opts?: Record<string, unknown>): string | Uint8Array;
+        writeFile(path: string, data: string | ArrayBufferView, opts?: Record<string, unknown>): void;
+        mkdirTree(path: string, mode?: number): void;
+        syncfs(populate: boolean, callback?: (err: unknown) => void): void;
+        analyzePath(path: string): {
+            exists: boolean;
+        };
+    };
+    unityPersistentDataPath?: string;
+}
+interface WavedashResponse<T> {
+    success: boolean;
+    data: T | null;
+    message?: string;
+}
+/** Payload for LobbyJoined event - emitted on successful lobby join or create */
+interface LobbyJoinedPayload {
+    lobbyId: GenericId<"lobbies">;
+    hostId: GenericId<"users">;
+    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];
+/** 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];
+/** Payload for LobbyUsersUpdated event - emitted when a user joins or leaves */
+interface LobbyUsersUpdatedPayload extends LobbyUser {
+    changeType: LobbyUserChangeType;
+}
+/** Payload for LobbyDataUpdated event - the full lobby metadata */
+type LobbyDataUpdatedPayload = Record<string, unknown>;
+/** Payload for LobbyMessage event - a message received in the lobby */
+type LobbyMessagePayload = LobbyMessage;
+/** Payload for LobbyInvite event - an invite to join a lobby */
+type LobbyInvitePayload = LobbyInvite;
+/** Payload for StatsStored event - emitted when stats/achievements are persisted */
+interface StatsStoredPayload {
+    success: boolean;
+    message?: string;
+}
+/** Payload for P2PConnectionEstablished event */
+interface P2PConnectionEstablishedPayload {
+    userId: GenericId<"users">;
+    username: string;
+}
+/** Payload for P2PConnectionFailed event */
+interface P2PConnectionFailedPayload {
+    userId: GenericId<"users">;
+    username: string;
+    error: string;
+}
+/** Payload for P2PPeerDisconnected event */
+interface P2PPeerDisconnectedPayload {
+    userId: GenericId<"users">;
+    username: string;
+}
+/** Payload for P2PPeerReconnecting event */
+interface P2PPeerReconnectingPayload {
+    userId: GenericId<"users">;
+    username: string;
+}
+/** Payload for P2PPeerReconnected event */
+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";
+/**
+ * Payload for P2PPacketDropped event.
+ *
+ * Emitted whenever the SDK drops a P2P packet — either outgoing (rejected
+ * by local validation) or incoming (rejected by the receive-side ring
+ * buffer / framing layer).
+ *
+ * Events are aggregated per `(channel, direction, reason)` tuple with a
+ * short window so bursty drops don't flood the game, while sparse drops
+ * still fire promptly.
+ */
+interface P2PPacketDroppedPayload {
+    channel: number;
+    direction: "SEND" | "RECEIVE";
+    reason: P2PPacketDropReason;
+    droppedCount: number;
+    droppedTotal: number;
+}
+/** Payload for BackendConnected, BackendDisconnected, BackendReconnecting events */
+interface BackendConnectionPayload {
+    isConnected: boolean;
+    hasEverConnected: boolean;
+    connectionCount: number;
+    connectionRetries: number;
+}
+interface P2PPeer {
+    userId: GenericId<"users">;
+    username: string;
+}
+interface P2PConnection {
+    lobbyId: GenericId<"lobbies">;
+    peers: Record<GenericId<"users">, P2PPeer>;
+}
+interface P2PMessage {
+    fromUserId: GenericId<"users">;
+    channel: number;
+    payload: Uint8Array;
+}
+interface P2PConfig {
+    enableReliableChannel: boolean;
+    enableUnreliableChannel: boolean;
+    messageSize?: number;
+    maxIncomingMessages?: number;
+}
+
+/**
+ * Lobby service
+ *
+ * Implements each of the lobby methods of the Wavedash SDK
+ */
+
+declare class LobbyManager {
+    private sdk;
+    private unsubscribeLobbyMessages;
+    private unsubscribeLobbyUsers;
+    private unsubscribeLobbyData;
+    private lobbyId;
+    private lobbyUsers;
+    private lobbyHostId;
+    private lobbyMetadata;
+    private pendingMetadataUpdates;
+    private recentMessageIds;
+    private maybeBeingDeletedLobbyIds;
+    private resetMaybeBeingDeletedLobbyIdTimeouts;
+    private cachedLobbies;
+    private unsubscribeLobbyInvites;
+    private seenInviteIds;
+    private p2pUpdateQueue;
+    constructor(sdk: WavedashSDK);
+    createLobby(visibility: LobbyVisibility, maxPlayers?: number): Promise<GenericId<"lobbies">>;
+    /**
+     * Join a lobby
+     * @param lobbyId - The ID of the lobby to join
+     * @returns true on success. Full lobby context comes via LobbyJoined event.
+     * @emits LobbyJoined event on success with full lobby context
+     */
+    joinLobby(lobbyId: GenericId<"lobbies">): Promise<boolean>;
+    getLobbyUsers(lobbyId: GenericId<"lobbies">): LobbyUser[];
+    getHostId(lobbyId: GenericId<"lobbies">): GenericId<"users"> | null;
+    getLobbyData(lobbyId: GenericId<"lobbies">, key: string): string | number | null;
+    deleteLobbyData(lobbyId: GenericId<"lobbies">, key: string): boolean;
+    private debouncedMetadataUpdate;
+    setLobbyData(lobbyId: GenericId<"lobbies">, key: string, value: string | number | null): boolean;
+    getLobbyMaxPlayers(lobbyId: GenericId<"lobbies">): number;
+    getNumLobbyUsers(lobbyId: GenericId<"lobbies">): number;
+    leaveLobby(lobbyId: GenericId<"lobbies">): Promise<GenericId<"lobbies">>;
+    listAvailableLobbies(friendsOnly?: boolean): Promise<Lobby[]>;
+    sendLobbyMessage(lobbyId: GenericId<"lobbies">, message: string): boolean;
+    inviteUserToLobby(lobbyId: GenericId<"lobbies">, userId: GenericId<"users">): Promise<boolean>;
+    getLobbyInviteLink(copyToClipboard?: boolean): Promise<string>;
+    /**
+     * Initialize local lobby state and subscribe to all relevant updates.
+     * Sets up Convex subscriptions for messages, users, and metadata.
+     * Emits LobbyJoined event to the game engine.
+     * @precondition - The user has already joined the lobby via mutation
+     * @param response - The full response from createAndJoinLobby or joinLobby mutation
+     */
+    private handleLobbyJoin;
+    /**
+     * Handle being kicked or removed from a lobby (subscription error)
+     * This is called when a subscription fails with "User is not a member of this lobby"
+     * Multiple subscriptions may error at once, so we guard against emitting multiple events
+     */
+    private handleLobbyKicked;
+    /**
+     * Clean up lobby state without emitting events
+     * Used internally by handleLobbyJoin() and handleLobbyKicked()
+     */
+    private cleanupLobbyState;
+    /**
+     * Public method to clean up lobby state without emitting events
+     * Used for session end cleanup
+     */
+    unsubscribeFromCurrentLobby(): void;
+    /**
+     * Fully destroy the LobbyManager, cleaning up all subscriptions and timeouts.
+     * Called during session end to ensure no lingering listeners.
+     */
+    destroy(): void;
+    private processPendingLobbyDataUpdates;
+    /**
+     * Process user updates and emit individual user events
+     * @param newUsers - The updated list of lobby users
+     */
+    private processUserUpdates;
+    private processMessageUpdates;
+    private processInviteUpdates;
+    /**
+     * Update P2P connections when lobby membership changes
+     * @param newUsers - The updated list of lobby users
+     */
+    private updateP2PConnections;
+}
+
+/**
+ * File system service
+ * Utilities for syncing local IndexedDB files with remote storage.
+ *
+ * Exposes a specific remote folder for the game to save user-specific files to.
+ * TODO: Extend this to game-level assets as well.
+ */
+
+declare class FileSystemManager {
+    private sdk;
+    private remoteStorageOrigin;
+    constructor(sdk: WavedashSDK);
+    /**
+     * Converts a local filesystem path into a full R2 object key.
+     * Normalizes the Unity persistentDataPath and prepends the R2 prefix.
+     */
+    private toRemoteKey;
+    /**
+     * Converts a full R2 object key back into the local filesystem path
+     * the engine expects. Inverse of toRemoteKey.
+     */
+    private toLocalPath;
+    /**
+     * Uploads a local file to remote storage
+     * @param filePath - The path of the local file to upload
+     * @returns The path of the remote file that the local file was uploaded to
+     */
+    uploadRemoteFile(filePath: string): Promise<string>;
+    /**
+     * Deletes a remote file from storage
+     * @param filePath - The path of the remote file to delete
+     * @returns The path of the remote file that was deleted
+     */
+    deleteRemoteFile(filePath: string): Promise<string>;
+    /**
+     * Downloads a remote file to a local location
+     * @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
+     * @param path - The path of the remote directory to list
+     * @returns A list of metadata for each file in the remote directory
+     */
+    listRemoteDirectory(path: string): Promise<RemoteFileMetadata[]>;
+    downloadRemoteDirectory(path: string): Promise<string>;
+    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>;
+    private getRemoteStorageOrigin;
+    private getRemoteStorageUrl;
+    private uploadFromIndexedDb;
+    private uploadFromFS;
+    private readLocalFileBlob;
+}
+
+/**
+ * UGC service
+ *
+ * Implements each of the user generated content methods of the Wavedash SDK
+ */
+
+declare class UGCManager {
+    private sdk;
+    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">>;
+    downloadUGCItem(ugcId: GenericId<"userGeneratedContent">, filePath: string): Promise<GenericId<"userGeneratedContent">>;
+}
+
+/**
+ * Leaderboard service
+ *
+ * Implements each of the leaderboard methods of the Wavedash SDK
+ */
+
+declare class LeaderboardManager {
+    private sdk;
+    private leaderboardCache;
+    constructor(sdk: WavedashSDK);
+    getLeaderboard(name: string): Promise<Leaderboard>;
+    getOrCreateLeaderboard(name: string, sortOrder: LeaderboardSortOrder, displayType: LeaderboardDisplayType): Promise<Leaderboard>;
+    getLeaderboardEntryCount(leaderboardId: GenericId<"leaderboards">): number;
+    getMyLeaderboardEntries(leaderboardId: GenericId<"leaderboards">): Promise<LeaderboardEntries>;
+    listLeaderboardEntriesAroundUser(leaderboardId: GenericId<"leaderboards">, countAhead: number, countBehind: number, friendsOnly?: boolean): Promise<LeaderboardEntries>;
+    listLeaderboardEntries(leaderboardId: GenericId<"leaderboards">, offset: number, limit: number, friendsOnly?: boolean): Promise<LeaderboardEntries>;
+    uploadLeaderboardScore(leaderboardId: GenericId<"leaderboards">, score: number, keepBest: boolean, ugcId?: GenericId<"userGeneratedContent">): Promise<UpsertedLeaderboardEntry>;
+    private updateCachedTotalEntries;
+}
+
+/**
+ * P2P networking service
+ *
+ * Handles WebRTC peer-to-peer connections for lobbies
+ */
+
+declare class P2PManager {
+    private sdk;
+    private config;
+    private currentConnection;
+    private peerConnections;
+    private reliableChannels;
+    private unreliableChannels;
+    private pendingIceCandidates;
+    private iceRestartAttempts;
+    private iceRestartInProgress;
+    private readonly MAX_ICE_RESTART_ATTEMPTS;
+    private reconnectingPeers;
+    private establishedPeers;
+    private packetDropTrackers;
+    private readonly PACKET_DROP_WINDOW_MS;
+    private turnCredentials;
+    private turnCredentialsInitPromise;
+    private unsubscribeFromSignalingMessages;
+    private processedSignalingMessages;
+    private pendingProcessedMessageIds;
+    private initializationInProgress;
+    private initializationLobbyId;
+    private signalingSubscriptionReady;
+    private signalingSubscriptionReadyResolver;
+    private channelQueues;
+    private readonly MESSAGE_SLOT_HEADER_SIZE;
+    private readonly MAX_CHANNELS;
+    private readonly USERID_SIZE;
+    private readonly CHANNEL_SIZE;
+    private readonly DATALENGTH_SIZE;
+    private readonly CHANNEL_OFFSET;
+    private readonly DATALENGTH_OFFSET;
+    private readonly PAYLOAD_OFFSET;
+    private readonly WIRE_CHANNEL_SIZE;
+    private readonly WIRE_CHANNEL_OFFSET;
+    private readonly WIRE_PAYLOAD_OFFSET;
+    private static readonly MAX_MESSAGE_SIZE;
+    private static readonly MEMORY_WARNING_THRESHOLD_BYTES;
+    private QUEUE_SIZE;
+    private MESSAGE_SIZE;
+    private MAX_PAYLOAD_SIZE;
+    private outgoingMessageBuffer;
+    private textEncoder;
+    private textDecoder;
+    private initialized;
+    constructor(sdk: WavedashSDK);
+    private ensureInitialized;
+    init(config?: Partial<P2PConfig>): void;
+    initializeP2PForCurrentLobby(lobbyId: GenericId<"lobbies">, members: SDKUser[]): Promise<P2PConnection>;
+    /**
+     * Internal method that performs the actual P2P initialization.
+     * Called by initializeP2PForCurrentLobby with proper locking.
+     */
+    private doInitializeP2P;
+    /**
+     * Get ICE servers, initializing TURN credentials if necessary.
+     * Uses a promise to debounce concurrent calls and prevent race conditions.
+     */
+    private getIceServers;
+    private updateP2PConnection;
+    private establishWebRTCConnections;
+    private subscribeToSignalingMessages;
+    private stopSignalingMessageSubscription;
+    private processSignalingMessages;
+    private handleSignalingMessage;
+    /**
+     * Flush any buffered ICE candidates for a peer after remote description is set.
+     * This handles the race condition where ICE candidates arrive before the offer/answer.
+     */
+    private flushPendingIceCandidates;
+    private establishPeerConnections;
+    private createOfferToPeer;
+    private createPeerConnection;
+    /**
+     * Attempt to restart ICE when connection fails.
+     * Only the peer with the lower userId initiates the restart to avoid conflicts.
+     */
+    private attemptIceRestart;
+    private setupDataChannelHandlers;
+    sendP2PMessage(toUserId: GenericId<"users"> | undefined, appChannel: number | undefined, reliable: boolean | undefined, payload: Uint8Array, payloadSize?: number): boolean;
+    private sendSignalingMessage;
+    disconnectP2P(): void;
+    isPeerReady(userId: GenericId<"users">): boolean;
+    isBroadcastReady(): boolean;
+    getPeerStatuses(): Record<GenericId<"users">, {
+        reliable?: string;
+        unreliable?: string;
+        ready: boolean;
+    }>;
+    private createChannelQueue;
+    /**
+     * Record a packet drop and emit P2P_PACKET_DROPPED with rate-limiting per
+     * (channel, direction, reason) tuple. First drop on an idle tuple fires
+     * immediately; subsequent drops within PACKET_DROP_WINDOW_MS are coalesced
+     * into a single event at the end of the window.
+     */
+    private reportPacketDrop;
+    private flushPacketDropWindow;
+    private emitPacketDropped;
+    private clearPacketDropTrackers;
+    private enqueueMessage;
+    getMaxPayloadSize(): number;
+    getMaxIncomingMessages(): number;
+    getOutgoingMessageBuffer(): Uint8Array;
+    readMessageFromChannel(appChannel: number): P2PMessage | null;
+    private readRawMessage;
+    drainChannelToBuffer(appChannel: number, buffer?: Uint8Array): Uint8Array;
+    private encodeWireMessage;
+    private decodeBinaryMessage;
+}
+
+type StatEntry = {
+    identifier: string;
+    value: number;
+};
+declare class StatsManager {
+    private sdk;
+    private stats;
+    private unlockedAchievements;
+    private dirtyStats;
+    private dirtyAchievements;
+    private knownStatIds;
+    private knownAchievementIds;
+    private loaded;
+    private subscriptions;
+    constructor(sdk: WavedashSDK);
+    destroy(): void;
+    private isReady;
+    private subscribe;
+    requestStats(): Promise<boolean>;
+    private debouncedPersist;
+    storeStats(): boolean;
+    private persist;
+    getStat(identifier: string): number;
+    setStat(identifier: string, value: number, storeNow?: boolean): boolean;
+    getAchievement(identifier: string): boolean;
+    setAchievement(identifier: string, storeNow?: boolean): boolean;
+    /** @destructive - Returns the pending stats and achievements and resets the dirty collections */
+    getPendingData(): {
+        stats: StatEntry[];
+        achievements: string[];
+    } | null;
+}
+
+/**
+ * Heartbeat service
+ *
+ * Polls connection state and allows the game to update rich user presence
+ * Lets the game know if backend connection ever changes.
+ * Lets the game update userPresence in the backend
+ */
+
+declare class HeartbeatManager {
+    private sdk;
+    private deviceFingerprint;
+    private deviceFingerprintReady;
+    private testConnectionInterval;
+    private heartbeatInterval;
+    private isConnected;
+    private sentDisconnectedEvent;
+    private disconnectedAt;
+    private lastHeartbeatTime;
+    private heartbeatInFlight;
+    private isFirstTick;
+    private readonly TEST_CONNECTION_INTERVAL_MS;
+    private readonly DISCONNECTED_TIMEOUT_MS;
+    constructor(sdk: WavedashSDK);
+    /** Start heartbeat and connection-check intervals */
+    start(): void;
+    /** Stop heartbeat and connection-check intervals */
+    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, unknown>): Promise<boolean>;
+    /**
+     * Tests the connection to the backend
+     */
+    private testConnection;
+    isCurrentlyConnected(): boolean;
+}
+
+declare class GameEventManager {
+    private sdk;
+    private eventQueue;
+    constructor(sdk: WavedashSDK);
+    notifyGame(event: WavedashEvent, payload: string | number | boolean | object): void;
+    private sendGameEvent;
+    flushEventQueue(): void;
+}
+
+/**
+ * Friends service
+ *
+ * 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;
+    constructor(sdk: WavedashSDK);
+    /**
+     * Cache users from any source (friends, lobby users)
+     * Accepts both Friend format (avatarUrl) and LobbyUser format (userAvatarUrl)
+     * @param users - Array of users with userId, username, and optional avatar r2Key
+     */
+    cacheUsers(users: Array<{
+        userId: GenericId<"users">;
+        username: string;
+        avatarUrl?: string;
+        userAvatarUrl?: string;
+    }>): void;
+    /**
+     * 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)
+     * @returns CDN URL with size transformation, or null if user not cached or has no avatar
+     */
+    getUserAvatarUrl(userId: GenericId<"users">, size?: number): string | null;
+    /**
+     * Returns the cached username for a given user ID
+     * @param userId - The user ID to get the username for
+     * @returns The username, or null if user not cached
+     */
+    getUsername(userId: GenericId<"users">): string | null;
+    listFriends(): Promise<Friend[]>;
+}
+
+/**
+ * Logger interface and implementation
+ * Simply logs to the console with customizable log level
+ *
+ * In the future we could extend this to write .log files to IndexedDB or cache storage
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+declare class WavedashLogger implements Logger {
+    private logLevel;
+    constructor(logLevel?: number);
+    setLogLevel(level: number): void;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Utilities for handling iframe messaging between the iframe'd Wavedash SDK and the parent window.
+ * Assumes window is defined and this is only ever running inside an iframe.
+ *
+ * TODO: Look into Vercel's BIDC for this https://github.com/vercel/bidc
+ */
+
+declare class IFrameMessenger {
+    private pendingRequests;
+    private requestIdCounter;
+    constructor();
+    private handleMessage;
+    postToParent(requestType: (typeof IFRAME_MESSAGE_TYPE)[keyof typeof IFRAME_MESSAGE_TYPE], data: Record<string, string | number | boolean>): boolean;
+    /**
+     * Register global keyboard/mouse handlers for iframe communication.
+     * Handles F3 prevention, initial interaction signaling, and Tab+Shift overlay toggle.
+     * Called once during SDK setup.
+     */
+    registerEventHandlers(): void;
+    requestFromParent<T extends keyof IFrameEventPayloadMap>(requestType: T, data?: Record<string, unknown>): Promise<IFrameEventPayloadMap[T]>;
+}
+
+declare class WavedashSDK extends EventTarget {
+    private _initialized;
+    get initialized(): boolean;
+    private _eventsReady;
+    get eventsReady(): boolean;
+    private launchParams;
+    private sessionEndSent;
+    private convexHttpUrl;
+    private gameFinishedLoading;
+    Events: {
+        readonly LOBBY_MESSAGE: "LobbyMessage";
+        readonly LOBBY_JOINED: "LobbyJoined";
+        readonly LOBBY_KICKED: "LobbyKicked";
+        readonly LOBBY_USERS_UPDATED: "LobbyUsersUpdated";
+        readonly LOBBY_DATA_UPDATED: "LobbyDataUpdated";
+        readonly LOBBY_INVITE: "LobbyInvite";
+        readonly P2P_CONNECTION_ESTABLISHED: "P2PConnectionEstablished";
+        readonly P2P_CONNECTION_FAILED: "P2PConnectionFailed";
+        readonly P2P_PEER_DISCONNECTED: "P2PPeerDisconnected";
+        readonly P2P_PEER_RECONNECTING: "P2PPeerReconnecting";
+        readonly P2P_PEER_RECONNECTED: "P2PPeerReconnected";
+        readonly P2P_PACKET_DROPPED: "P2PPacketDropped";
+        readonly STATS_STORED: "StatsStored";
+        readonly BACKEND_CONNECTED: "BackendConnected";
+        readonly BACKEND_DISCONNECTED: "BackendDisconnected";
+        readonly BACKEND_RECONNECTING: "BackendReconnecting";
+    };
+    protected lobbyManager: LobbyManager;
+    protected statsManager: StatsManager;
+    protected heartbeatManager: HeartbeatManager;
+    protected ugcManager: UGCManager;
+    protected leaderboardManager: LeaderboardManager;
+    gameEventManager: GameEventManager;
+    friendsManager: FriendsManager;
+    config: WavedashConfig | null;
+    wavedashUser: SDKUser;
+    gameCloudId: string;
+    fileSystemManager: FileSystemManager;
+    convexClient: ConvexClient;
+    engineCallbackReceiver: string;
+    engineInstance: EngineInstance | null;
+    logger: WavedashLogger;
+    iframeMessenger: IFrameMessenger;
+    p2pManager: P2PManager;
+    private gameplayJwt;
+    private gameplayJwtPromise;
+    ugcHost: string;
+    uploadsHost: string;
+    constructor(sdkConfig: SDKConfig);
+    init(config?: WavedashConfig): boolean;
+    /**
+     * Signal that the game is ready to receive events (LobbyJoined, LobbyMessage, etc).
+     * Called automatically by init() unless deferEvents: true is passed in the config.
+     * If deferEvents is true, call this manually after your pre-game setup is complete.
+     */
+    readyForEvents(): void;
+    loadScript(src: string): Promise<unknown>;
+    updateLoadProgressZeroToOne(progress: number): void;
+    loadComplete(): void;
+    get gameLoaded(): boolean;
+    toggleOverlay(): void;
+    getUser(): SDKUser;
+    /**
+     * Get a username. Returns the logged in user's username if no ID is passed.
+     * This can only return a username for a user the game has already interacted with, either via listFriends() or shared lobby membership.
+     * @param userId - Optional user ID to look up. If omitted, returns the current user's username.
+     * @returns The username, or null if a userId was passed but the user has not been seen by the game yet.
+     */
+    getUsername(): string;
+    getUsername(userId: GenericId<"users">): string | null;
+    getUserId(): GenericId<"users">;
+    /**
+     * Get the current user's gameplay JWT, fetching it if not already cached.
+     * This should be used to authenticate requests to your game's own backend,
+     * if you have one.
+     * @returns The user's JWT signed by the Wavedash backend
+     */
+    getUserJwt(): Promise<WavedashResponse<string>>;
+    /**
+     * Get the key: value mapping of all URL query params present when the game was launched
+     * lobby - The lobby ID to join if the user launched with the intention to join a lobby
+     * @returns Dictionary of the URL query params that were present when the game was launched
+     */
+    getLaunchParams(): GameLaunchParams;
+    listFriends(): Promise<WavedashResponse<Friend[]>>;
+    /**
+     * 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)
+     * @returns CDN URL with size transformation, or null if user not cached or has no avatar
+     */
+    getUserAvatarUrl(userId: GenericId<"users">, size?: number): string | null;
+    getLeaderboard(name: string): Promise<WavedashResponse<Leaderboard>>;
+    getOrCreateLeaderboard(name: string, sortOrder: LeaderboardSortOrder, displayType: LeaderboardDisplayType): Promise<WavedashResponse<Leaderboard>>;
+    getLeaderboardEntryCount(leaderboardId: GenericId<"leaderboards">): number;
+    getMyLeaderboardEntries(leaderboardId: GenericId<"leaderboards">): Promise<WavedashResponse<LeaderboardEntries>>;
+    listLeaderboardEntriesAroundUser(leaderboardId: GenericId<"leaderboards">, countAhead: number, countBehind: number, friendsOnly?: boolean): Promise<WavedashResponse<LeaderboardEntries>>;
+    listLeaderboardEntries(leaderboardId: GenericId<"leaderboards">, offset: number, limit: number, friendsOnly?: boolean): Promise<WavedashResponse<LeaderboardEntries>>;
+    uploadLeaderboardScore(leaderboardId: GenericId<"leaderboards">, score: number, keepBest: boolean, ugcId?: GenericId<"userGeneratedContent">): Promise<WavedashResponse<UpsertedLeaderboardEntry>>;
+    /**
+     * Creates a new UGC item and uploads the file to the server if a filePath is provided
+     * @param ugcType
+     * @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 created but no file will be uploaded.
+     * @returns ugcId
+     */
+    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.
+     * @returns ugcId
+     */
+    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
+    downloadUGCItem(ugcId: GenericId<"userGeneratedContent">, filePath: string): Promise<WavedashResponse<GenericId<"userGeneratedContent">>>;
+    /**
+     * Deletes a remote file from storage
+     * @param filePath - The path of the remote file to delete
+     * @returns The path of the remote file that was deleted
+     */
+    deleteRemoteFile(filePath: string): Promise<WavedashResponse<string>>;
+    /**
+     * Downloads a remote file to a local location
+     * @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>>;
+    /**
+     * Uploads a local file to remote storage
+     * @param filePath - The path of the local file to upload
+     * @param uploadTo - Optionally provide a path to upload the file to, defaults to the same path as the local file
+     * @returns The path of the remote file that the local file was uploaded to
+     */
+    uploadRemoteFile(filePath: string): Promise<WavedashResponse<string>>;
+    /**
+     * Lists a remote directory
+     * @param path - The path of the remote directory to list
+     * @returns A list of metadata for each file in the remote directory
+     */
+    listRemoteDirectory(path: string): Promise<WavedashResponse<RemoteFileMetadata[]>>;
+    /**
+     * Downloads a remote directory to a local location
+     * @param path - The path of the remote directory to download
+     * @returns The path of the local directory that the remote directory was downloaded to
+     */
+    downloadRemoteDirectory(path: string): Promise<WavedashResponse<string>>;
+    /**
+     * Persists data to local file storage (IndexeDB).
+     * For use in pure JS games.
+     * Games built from engines should use their engine's builtin File API to read and write files.
+     * @param filePath - The path of the local file to write
+     * @param data - The data to write to the local file (byte array)
+     * @returns true if the file was written successfully
+     */
+    writeLocalFile(filePath: string, data: Uint8Array): Promise<boolean>;
+    /**
+     * Reads data from local file storage (IndexedDB).
+     * For use in pure JS games.
+     * Games built from engines should use their engine's builtin File API to read and write files.
+     * @param filePath - The path of the local file to read
+     * @returns The data read from the local file (byte array)
+     */
+    readLocalFile(filePath: string): Promise<Uint8Array | null>;
+    getAchievement(identifier: string): boolean;
+    getStat(identifier: string): number;
+    setAchievement(identifier: string, storeNow?: boolean): boolean;
+    setStat(identifier: string, value: number, storeNow?: boolean): boolean;
+    requestStats(): Promise<WavedashResponse<boolean>>;
+    storeStats(): boolean;
+    /**
+     * Get the maximum payload size in bytes for a single P2P message.
+     * This is derived from the configured messageSize minus protocol overhead.
+     */
+    getP2PMaxPayloadSize(): number;
+    /**
+     * Get the configured max incoming messages per channel queue.
+     */
+    getP2PMaxIncomingMessages(): number;
+    /**
+     * Get a pre-allocated scratch buffer for outgoing messages
+     * @returns A Uint8Array buffer that can your game can write the binary payload to before calling sendP2PMessage
+     */
+    getP2POutgoingMessageBuffer(): Uint8Array;
+    /**
+     * Send a message through P2P to a specific peer using their userId
+     * @param toUserId - Peer userId to send to (undefined = broadcast)
+     * @param appChannel - Optional channel for message routing. All messages still use the same P2P connection under the hood.
+     * @param reliable - Send reliably, meaning guaranteed delivery and ordering, but slower (default: true)
+     * @param payload - The payload to send (byte array)
+     * @param payloadSize - How many bytes from the payload to send. Defaults to payload.length (the entire payload)
+     * @returns true if the message was sent out successfully
+     */
+    sendP2PMessage(toUserId: GenericId<"users"> | undefined, appChannel: number | undefined, reliable: boolean | undefined, payload: Uint8Array, payloadSize?: number): boolean;
+    /**
+     * Send the same payload to all peers in the lobby
+     * @param appChannel - Optional app-level channel for message routing. All messages still use the same P2P connection under the hood.
+     * @param reliable - Send reliably, meaning guaranteed delivery and ordering, but slower (default: true)
+     * @param payload - The payload to send (byte array)
+     * @param payloadSize - How many bytes from the payload to send. Defaults to payload.length (the entire payload)
+     * @returns true if the message was sent out successfully
+     */
+    broadcastP2PMessage(appChannel: number | undefined, reliable: boolean | undefined, payload: Uint8Array, payloadSize?: number): boolean;
+    /**
+     * Read one decoded P2P message from a specific channel.
+     * Engine builds (Unity/Godot) should use drainP2PChannelToBuffer for the
+     * hot path — it's batched and returns raw bytes without decode overhead.
+     * @param appChannel - The channel to read from
+     * @returns Decoded P2PMessage, or null if the channel has no pending messages.
+     */
+    readP2PMessageFromChannel(appChannel: number): P2PMessage | null;
+    /**
+     * Drain all messages from a P2P channel into a buffer
+     * Data will be presented in a tightly packed format: [size:4 bytes][msg:N bytes][size:4 bytes][msg:N bytes]...
+     * JS games can just use readP2PMessageFromChannel to get decoded P2PMessages
+     * Game engines should use drainP2PChannelToBuffer for better performance
+     * @param appChannel - The channel to drain
+     * @param buffer - The buffer to drain the messages into.
+     *  If provided, the buffer will be filled until full, any remaining messages will be left in the queue.
+     *  If not provided, a new buffer with all messages will be created and returned.
+     * @returns A Uint8Array containing each message in a tightly packed format: [size:4 bytes][msg:N bytes][size:4 bytes][msg:N bytes]...
+     */
+    drainP2PChannelToBuffer(appChannel: number, buffer?: Uint8Array): Uint8Array;
+    /**
+     * Create a new lobby and join it as the host.
+     * @param visibility - The visibility of the lobby
+     * @param maxPlayers - Optional maximum number of players
+     * @returns A WavedashResponse with the created lobbyId.
+     *          Full lobby context is provided via the LobbyJoined event.
+     * @emits LobbyJoined event on success with full lobby context
+     */
+    createLobby(visibility: LobbyVisibility, maxPlayers?: number): Promise<WavedashResponse<GenericId<"lobbies">>>;
+    /**
+     * Join an existing lobby.
+     * @param lobbyId - The ID of the lobby to join
+     * @returns A WavedashResponse with success/failure.
+     *          Full lobby context is provided via the LobbyJoined event.
+     * @emits LobbyJoined event on success with full lobby context
+     */
+    joinLobby(lobbyId: GenericId<"lobbies">): Promise<WavedashResponse<boolean>>;
+    listAvailableLobbies(friendsOnly?: boolean): Promise<WavedashResponse<Lobby[]>>;
+    getLobbyUsers(lobbyId: GenericId<"lobbies">): LobbyUser[];
+    getNumLobbyUsers(lobbyId: GenericId<"lobbies">): number;
+    getLobbyHostId(lobbyId: GenericId<"lobbies">): GenericId<"users"> | null;
+    getLobbyData(lobbyId: GenericId<"lobbies">, key: string): string | number | null;
+    setLobbyData(lobbyId: GenericId<"lobbies">, key: string, value: string | number | null): boolean;
+    deleteLobbyData(lobbyId: GenericId<"lobbies">, key: string): boolean;
+    leaveLobby(lobbyId: GenericId<"lobbies">): Promise<WavedashResponse<GenericId<"lobbies">>>;
+    sendLobbyMessage(lobbyId: GenericId<"lobbies">, message: string): boolean;
+    inviteUserToLobby(lobbyId: GenericId<"lobbies">, userId: GenericId<"users">): Promise<WavedashResponse<boolean>>;
+    getLobbyInviteLink(copyToClipboard?: boolean): Promise<WavedashResponse<string>>;
+    /**
+     * Updates rich user presence so friends can see what the player is doing in game
+     * 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>>;
+    private isGodot;
+    private formatResponse;
+    private ensureInit;
+    private apiCall;
+    private apiCallSync;
+    /**
+     * Fetches (or returns cached) gameplay JWT. Callers outside of Convex's
+     * setAuth should use {@link ensureGameplayJwt} instead; this method is the
+     * fetcher wired into `ConvexClient.setAuth` and honors `forceRefresh` so the
+     * server can invalidate a stale token.
+     *
+     * Concurrent callers share a single in-flight fetch to avoid duplicate
+     * requests to the parent's gameplay-token endpoint.
+     */
+    private getAuthToken;
+    /**
+     * Returns the cached gameplay JWT, awaiting the in-flight fetch if one is
+     * already running (e.g. from Convex's initial setAuth). Use this anywhere
+     * you need to authenticate a request outside of the Convex client.
+     */
+    ensureGameplayJwt(): Promise<string>;
+    /**
+     * Set up listeners for page unload events to end gameplay session.
+     * Uses both beforeunload and pagehide for maximum reliability.
+     */
+    private setupSessionEndListeners;
+}
+
+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 };