Types reference

import type { UserId, LobbyId, LeaderboardId, UGCId, PurchaseId } from "@wvdsh/sdk-js";

type WavedashResponse<T> =
  | { success: true; data: T }                       // Success: data holds the result
  | { success: false; data: null; message: string }; // Failure: message explains why

import type { Leaderboard } from "@wvdsh/sdk-js";

const user = Wavedash.getUser(); // sync getter

const response = await Wavedash.getLeaderboard("high-scores");

if (response.success) {
  const leaderboard: Leaderboard = response.data;
  // Use leaderboard...
} else {
  console.error(response.message);
}

interface User {
  id: UserId;                  // The player's user ID
  username: string;                 // Display name
  avatarUrl: string | undefined;    // Avatar URL (if set)
}

interface WavedashConfig {
  debug?: boolean;                       // Useful for logging and testing — enables verbose output in the browser console
  deferEvents?: boolean;                 // Queues all SDK events until readyForEvents() is called
  p2p?: Partial<P2PConfig>;             // P2P networking configuration (see P2PConfig below)
}

interface P2PConfig {
  enableReliableChannel: boolean;  // TCP-like channel
  enableUnreliableChannel: boolean; // UDP-like channel
  messageSize?: number;            // Max bytes per message slot (default: 2048, max: 65536)
  maxIncomingMessages?: number;    // Incoming message queue depth (default: 1024)
}

interface GameLaunchParams {
  lobby?: LobbyId;       // Lobby ID if the player followed an invite link
  [key: string]: string | undefined; // Any other wvdsh_-prefixed params
}

interface Leaderboard {
  id: LeaderboardId;              // Leaderboard ID
  name: string;                        // The identifier you pass to getLeaderboard / getOrCreateLeaderboard
  totalEntries: number;                // Total number of entries
}

// 0 = ascending  — Lower scores rank higher (time trials, golf)
// 1 = descending — Higher scores rank higher (points, high scores)
type LeaderboardSortOrder = 0 | 1;

// 0 = numeric           — Display as a number (e.g., "1,000")
// 1 = time_seconds      — Display as time in seconds (e.g., "1:23")
// 2 = time_milliseconds — Display as time with milliseconds (e.g., "1:23.456")
// 3 = time_game_ticks   — Display as game ticks (assumes 60fps)
type LeaderboardDisplayType = 0 | 1 | 2 | 3;

interface LeaderboardEntry {
  userId: UserId;                  // Player's user ID
  username: string;                     // Player's display name
  userAvatarUrl?: string;               // Player's avatar URL (if set)
  score: number;                        // Score value
  globalRank: number;                   // Current rank
  ugcId?: UGCId;   // Attached UGC (optional)
  timestamp: number;                    // Submission timestamp
  metadata?: LeaderboardEntryMetadata;  // Data stored with the score (optional)
}

type LeaderboardEntryMetadata = Record<string, string | number | boolean>;

interface UpsertedLeaderboardEntry {
  entryId: LeaderboardEntryId;
  score: number;                        // Your saved standing's score
  scoreChanged: boolean;                // false if keepBest kept a better score
  globalRank: number;                   // Your saved standing's rank
  submittedScore: number;               // The score you just submitted
  submittedRank: number;                // Where that submitted run would rank
  timestamp: number;                    // When the saved entry was recorded
  ugcId?: UGCId;   // UGC attached to the saved entry
  metadata?: LeaderboardEntryMetadata;  // The metadata now stored on the entry
  userId: UserId;
  username: string;
  userAvatarUrl?: string;
}

interface Lobby {
  lobbyId: LobbyId;            // Lobby ID
  visibility: LobbyVisibility;       // Access level
  maxPlayers: number;                // Player limit
  playerCount: number;               // Current count
  metadata: Record<string, LobbyDataValue>; // Host-set key/value data
}

type LobbyDataValue = string | number | boolean;

type LobbyDataUpdate = LobbyDataValue | null;

// 0 = public       — Anyone can find and join
// 1 = friends_only — Listed only to friends; anyone with the ID can join
// 2 = private      — Only joinable with the lobby ID
type LobbyVisibility = 0 | 1 | 2;

interface LobbyUser {
  lobbyId: LobbyId;       // Lobby ID
  userId: UserId;          // User ID
  username: string;             // Display name
  userAvatarUrl?: string;       // Avatar URL
  isHost: boolean;              // Whether this user is the host
}

interface LobbyMessage {
  messageId: LobbyMessageId; // Message ID
  lobbyId: LobbyId;       // Lobby ID
  userId: UserId;          // Sender's ID
  username: string;             // Sender's name
  message: string;              // Message text
  timestamp: number;            // Timestamp
}

interface LobbyInvite {
  notificationId: LobbyInviteId; // Notification ID
  lobbyId: LobbyId;       // ID of the lobby you're invited to
  sender: {
    _id: UserId;           // User ID of who sent the invite
    username: string;           // Username of who sent the invite
    avatarUrl?: string;         // Avatar URL of the sender
  };
  _creationTime: number;        // When the invite was sent
}

interface Friend {
  userId: UserId;   // Friend's user ID
  username: string;      // Friend's display name
  avatarUrl?: string;    // Avatar URL (if set)
  isOnline: boolean;     // Whether the friend is currently online
}

interface P2PConnection {
  lobbyId: LobbyId;
  peers: Record<UserId, P2PPeer>;
}

interface P2PPeer {
  userId: UserId;   // Peer's user ID
  username: string;      // Peer's display name
}

interface P2PMessage {
  fromUserId: UserId;   // Sender's user ID
  channel: number;           // Channel number (0-7)
  payload: Uint8Array;  // Binary data
}

// UGC types are integer values:
// 0 = SCREENSHOT    - Player-captured screenshot
// 1 = VIDEO         - Player-captured video
// 2 = COMMUNITY     - Community-created content (levels, mods, etc.)
// 3 = GAME_MANAGED  - Game-managed content (replays, saves)
// 4 = OTHER         - Other UGC types
type UGCType = 0 | 1 | 2 | 3 | 4;

// UGC visibility is an integer value:
// 0 = PUBLIC  - Anyone can view
// 2 = PRIVATE - Only the creator can view
type UGCVisibility = 0 | 2;

interface Purchase {
  purchaseId: PurchaseId;       // Dedupe on this; pass it to fulfillPurchase
  contentIdentifier: string;    // The offer's content identifier
  type: PurchaseType;
  fulfilled: boolean;           // false for a consumable awaiting fulfillPurchase
  purchasedAt: number;          // Milliseconds since epoch
  receiptJwt: string;           // Signed receipt to verify on your backend
}

type PurchaseCompletedPayload = Purchase;

type PurchaseType = "DURABLE" | "CONSUMABLE";

interface FulfillPurchaseResult {
  status: "FULFILLED" | "ALREADY_FULFILLED" | "NOT_FOUND";
}

interface RemoteFileMetadata {
  exists: boolean;     // Whether file exists
  key: string;         // Full storage key
  name: string;        // Filename
  lastModified: number; // Unix timestamp in seconds
  size: number;        // Size in bytes
  etag: string;        // Version identifier
}

interface EngineInstance {
  type: "GODOT" | "UNITY" | "UNREAL" | "JSDOS" | "RUFFLE" | "RENPY" | "CUSTOM";

  // Send message to engine
  SendMessage(
    objectName: string,
    methodName: WavedashEvent,
    value?: string | number
  ): void;

  // Emscripten filesystem API
  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 };
  };

  // Unity only: Application.persistentDataPath
  unityPersistentDataPath?: string;
}

// Header: { alg: "RS256", kid: string, typ: "JWT" }
interface UserJwtPayload {
  iss: "https://auth.wavedash.com";
  aud: "gameplay.wavedash.com";
  sub: string;      // Wavedash user ID: the player's stable identity, same as getUserId()
  scope: "gameplay";
  gbid: string;     // Game build ID the player is running
  r2key?: string;   // Storage key of the uploaded build (uploaded builds only)
  gcid: string;     // Game cloud ID: your game in one environment (playtest or production)
  ents: string[];   // Durable content identifiers the player owns (what isEntitled reads)
  iat: number;      // Issued at (seconds since epoch)
  nbf: number;      // Not before (seconds since epoch), 60 seconds before iat for clock skew
  exp: number;      // Expiry (seconds since epoch), 1 hour after iat
}

// Header: { alg: "RS256", kid: string, typ: "wavedash-purchase+jwt" }
interface PurchaseReceiptPayload {
  iss: "https://auth.wavedash.com";
  aud: string;               // Your game's ID (game_id in wavedash.toml)
  sub: string;               // Wavedash user ID of the buyer, same as the user JWT's sub
  env: "PRODUCTION" | "PLAYTEST";
  gcid: string;              // Game cloud ID, same as the user JWT's gcid in that environment
  event: "purchase.completed" | "purchase.refunded";
  purchaseId: PurchaseId;    // Same as Purchase.purchaseId; dedupe grants on it
  ptype: PurchaseType;    // "DURABLE" or "CONSUMABLE"
  contentIdentifier: string; // The offer that was bought
  created: number;           // When the event happened: the purchase, or the refund (seconds since epoch)
  iat: number;               // When this receipt was signed (seconds since epoch)
  jti?: string;              // Webhook deliveries only: the delivery ID, stable across retries and resends
}