@usions/sdk 2.11.1 → 2.13.0

package/types/index.d.ts

@@ -24,6 +24,13 @@ export interface UsionConfig {
   serviceName?: string;
   apiUrl?: string;
   connectionMode?: 'platform' | 'direct';
+  /**
+   * Internal path the host opened this app at — set when the user taps a
+   * notification carrying a `path`. Read via `Usion.getLaunchParams().path`.
+   */
+  launchPath?: string;
+  /** Referral code the app was opened with, if any. */
+  ref?: string;
 }
 
 // ─── Payment ─────────────────────────────────────────────────────
@@ -76,7 +83,7 @@ export interface WalletModule {
   getBalance(): Promise<number>;
   hasCredits(amount: number): Promise<boolean>;
   requestPayment(amount: number, reason: string, data?: Record<string, any>): Promise<PaymentResponse>;
-  onBalanceChange(callback: (balance: number) => void): void;
+  onBalanceChange(callback: (balance: number) => void): UnsubscribeFn;
 }
 
 // ─── Session ─────────────────────────────────────────────────────
@@ -178,6 +185,38 @@ export interface GameActionData {
   action_type: string;
   action_data: Record<string, any>;
   sequence?: number;
+  /** Present when the sender passed { nextTurn } — the server-remembered turn. */
+  current_turn?: string;
+}
+
+/** Returned by event registrations; call to remove the handler. */
+export type UnsubscribeFn = () => void;
+
+export interface GameActionOptions {
+  /**
+   * Player ID whose turn comes after this action. The server stores it (no
+   * game logic — a relay that remembers) and returns it as current_turn in
+   * join acks and game:sync, so turn state survives reconnects.
+   */
+  nextTurn?: string;
+  /**
+   * Hold this action while disconnected and send it (in order) once the
+   * connection recovers, instead of rejecting with NOT_CONNECTED — "your
+   * move is saved and sends when you're back". For turn-based games only;
+   * never queue realtime-style inputs. Queue cap 20 (then QUEUE_FULL).
+   */
+  queueOffline?: boolean;
+}
+
+export interface PlayerConnectionData {
+  room_id: string;
+  player_id: string;
+  /**
+   * connected     — player (re)joined the room.
+   * reconnecting  — player's connection dropped; grace window running (~15s).
+   * gone          — player did not return before the grace/heartbeat expiry.
+   */
+  state: 'connected' | 'reconnecting' | 'gone';
 }
 
 export interface GameFinishedData {
@@ -191,6 +230,7 @@ export interface SyncData {
   room_id: string;
   actions: GameActionData[];
   game_state: Record<string, any>;
+  current_turn?: string | null;
   sequence: number;
 }
 
@@ -207,14 +247,35 @@ export interface GameModule {
   isConnected(): boolean;
 
   // Room & actions
+  //
+  // RELIABILITY CONTRACT (what the platform guarantees / what your game must do):
+  // - Every action is echoed back to the sender with the authoritative
+  //   sequence number. Apply game state ONLY in onAction — never
+  //   optimistically on send — so all clients apply identical actions in
+  //   identical order. The SDK deduplicates by sequence, so each action is
+  //   delivered exactly once even across reconnect replays.
+  // - On a connection blip the host/SDK rejoins the room and replays missed
+  //   actions via onSync automatically. Use onDisconnect/onReconnect to
+  //   pause input and show a "reconnecting" indicator.
+  // - For turn-based games, pass { nextTurn } on each move and trust
+  //   current_turn from join/sync instead of deriving the turn locally.
+  // - The room authority (player_ids[0]) should checkpoint via setState()
+  //   at meaningful transitions so rejoining clients can restore instantly.
   join(roomId?: string): Promise<GameJoinResult>;
   leave(): void;
-  action(actionType: string, actionData?: Record<string, any>): Promise<ActionResult>;
+  action(actionType: string, actionData?: Record<string, any>, opts?: GameActionOptions): Promise<ActionResult>;
   realtime(actionType: string, actionData?: Record<string, any>): void;
   requestSync(lastSequence?: number): void;
   requestRematch(): void;
   forfeit(): Promise<{ success: boolean; error?: string }>;
 
+  /**
+   * Checkpoint authoritative game state on the server (authority only —
+   * player_ids[0]/host). (Re)joining clients receive the latest checkpoint
+   * as game_state in the join ack and in game:sync. Max 64 KB serialized.
+   */
+  setState(state: Record<string, any>): Promise<{ success: boolean; error?: string; code?: UsionErrorCode }>;
+
   // Persisted state — survives iframe unmount/remount.
   // Keyed by (player_id, room_id) in localStorage. Schema is up to the game.
   saveState<T = any>(state: T): boolean;
@@ -226,23 +287,31 @@ export interface GameModule {
   debug(payload: Record<string, any>): void;
 
   // Event handlers
-  onJoined(callback: (data: GameJoinResult) => void): void;
-  onPlayerJoined(callback: (data: PlayerJoinedData) => void): void;
-  onPlayerLeft(callback: (data: PlayerLeftData) => void): void;
-  onStateUpdate(callback: (data: StateUpdateData) => void): void;
-  onSync(callback: (data: SyncData) => void): void;
-  onAction(callback: (data: GameActionData) => void): void;
-  onRealtime(callback: (data: Record<string, any>) => void): void;
-  onGameFinished(callback: (data: GameFinishedData) => void): void;
-  onGameRestarted(callback: (data: Record<string, any>) => void): void;
-  onError(callback: (data: { message: string; code?: string }) => void): void;
-  onRematchRequest(callback: (data: RematchData) => void): void;
-  onDisconnect(callback: (reason: string) => void): void;
-  onReconnect(callback: (attemptNumber: number) => void): void;
-  onConnectionError(callback: (error: Error) => void): void;
-
-  // Generic event listener
-  on(event: string, callback: (data: any) => void): void;
+  onJoined(callback: (data: GameJoinResult) => void): UnsubscribeFn;
+  onPlayerJoined(callback: (data: PlayerJoinedData) => void): UnsubscribeFn;
+  onPlayerLeft(callback: (data: PlayerLeftData) => void): UnsubscribeFn;
+  onStateUpdate(callback: (data: StateUpdateData) => void): UnsubscribeFn;
+  onSync(callback: (data: SyncData) => void): UnsubscribeFn;
+  onAction(callback: (data: GameActionData) => void): UnsubscribeFn;
+  onRealtime(callback: (data: Record<string, any>) => void): UnsubscribeFn;
+  onGameFinished(callback: (data: GameFinishedData) => void): UnsubscribeFn;
+  onGameRestarted(callback: (data: Record<string, any>) => void): UnsubscribeFn;
+  onError(callback: (data: { message: string; code?: string }) => void): UnsubscribeFn;
+  onRematchRequest(callback: (data: RematchData) => void): UnsubscribeFn;
+  onDisconnect(callback: (reason: string) => void): UnsubscribeFn;
+  onReconnect(callback: (attemptNumber: number) => void): UnsubscribeFn;
+  onConnectionError(callback: (error: Error) => void): UnsubscribeFn;
+  /** Peer connection lifecycle: connected / reconnecting (grace) / gone. */
+  onPlayerConnection(callback: (data: PlayerConnectionData) => void): UnsubscribeFn;
+
+  /**
+   * Register an ADDITIONAL event listener. Unlike the onX methods this
+   * supports multiple listeners per event, can be called before connect(),
+   * and works in every transport. Accepts internal names ('action'), wire
+   * names ('game:action'), or snake_case ('player_joined').
+   * @returns Unsubscribe function.
+   */
+  on(event: string, callback: (data: any) => void): UnsubscribeFn;
 
   // ─── Netcode helpers (low-latency realtime) ──────────────────
   // JSON state delta compression.
@@ -667,7 +736,7 @@ export interface BotModule {
   sendMessage(text: string): void;
   updateContext(ctx: Record<string, any>): void;
   close(result?: any): void;
-  onMessage(callback: (message: BotMessage) => void): void;
+  onMessage(callback: (message: BotMessage) => void): UnsubscribeFn;
 }
 
 // ─── Selection Grid ──────────────────────────────────────────────
@@ -691,6 +760,13 @@ export interface UsionSDK {
   getTheme(): 'light' | 'dark';
   getLanguage(): string;
 
+  /**
+   * Launch parameters the host opened this app with. `path` is the deep-link
+   * target (e.g. from a tapped `Usion.notify` notification); route to it after
+   * init so the user lands on the right screen.
+   */
+  getLaunchParams(): { path: string | null; ref: string | null; roomId: string | null };
+
   // Payments
   requestPayment(amount: number, reason: string, data?: Record<string, any>): Promise<PaymentResponse>;
 
@@ -733,6 +809,29 @@ export interface UsionSDK {
     onChange: (selected: string, item: HTMLElement) => void
   ): SelectionGrid;
 
+  /** SDK version (injected from package.json at build time). */
+  version: string;
+
+  /**
+   * Live diagnostics snapshot: version, transport, connection + sequence
+   * state. game.debug() attaches this automatically as payload._diag.
+   */
+  diagnostics(): {
+    version: string;
+    transport: 'socket' | 'proxy' | 'direct' | 'none';
+    connected: boolean;
+    joined: boolean;
+    roomId: string | null;
+    playerId: string | null;
+    lastSequence: number;
+    lastActionApplied: number;
+    rejoining: boolean;
+  };
+
+  // Errors — branch on err.code (stable), never on message text.
+  UsionError: typeof UsionError;
+  ERROR_CODES: typeof ERROR_CODES;
+
   // Modules
   user: UserModule;
   storage: StorageModule;
@@ -746,9 +845,24 @@ export interface UsionSDK {
   leaderboard: LeaderboardModule;
   matchmaking: MatchmakingModule;
   cloud: CloudModule;
+  notify: NotifyModule;
   netcode: NetcodeModule;
 }
 
+/**
+ * Send notifications to the CURRENT user that reopen this app (in-app banner
+ * when online, OS push when offline). `path` deep-links to a screen, read back
+ * via `Usion.getLaunchParams().path`. Rate-limited per user per service.
+ */
+export interface NotifyModule {
+  /** Notify the current user. */
+  send(opts: { title: string; body: string; path?: string; serviceId?: string }): Promise<{ success: boolean; delivered?: string }>;
+  /** Mute/unmute notifications from this app for the current user. */
+  setMuted(muted: boolean, opts?: { serviceId?: string }): Promise<{ success: boolean; muted: boolean }>;
+  /** Whether the current user has muted this app's notifications. */
+  isMuted(opts?: { serviceId?: string }): Promise<boolean>;
+}
+
 /** Scoped server-persisted KV operations (per-user or shared). */
 export interface CloudScope {
   /** Get a value; resolves to null when the key doesn't exist. */
@@ -822,6 +936,38 @@ export interface LobbyModule {
   queue(serviceId: string, opts?: { conversationId?: string }): Promise<any>;
 }
 
+/**
+ * Stable machine-readable error codes. Part of the public API: codes are
+ * never removed within a major version. Messages may change — branch on
+ * `err.code`, never on message text.
+ */
+export declare const ERROR_CODES: {
+  readonly NOT_CONNECTED: 'NOT_CONNECTED';
+  readonly NO_ROOM: 'NO_ROOM';
+  readonly ROOM_NOT_FOUND: 'ROOM_NOT_FOUND';
+  readonly NOT_PARTICIPANT: 'NOT_PARTICIPANT';
+  readonly NOT_AUTHORITY: 'NOT_AUTHORITY';
+  readonly NOT_AUTHENTICATED: 'NOT_AUTHENTICATED';
+  readonly JOIN_TIMEOUT: 'JOIN_TIMEOUT';
+  readonly CONNECT_TIMEOUT: 'CONNECT_TIMEOUT';
+  readonly STATE_TOO_LARGE: 'STATE_TOO_LARGE';
+  readonly INVALID_STATE: 'INVALID_STATE';
+  readonly INVALID_NEXT_TURN: 'INVALID_NEXT_TURN';
+  readonly RATE_LIMITED: 'RATE_LIMITED';
+  readonly REQUEST_TIMEOUT: 'REQUEST_TIMEOUT';
+  readonly QUEUE_FULL: 'QUEUE_FULL';
+  readonly UNSUPPORTED: 'UNSUPPORTED';
+  readonly UNKNOWN: 'UNKNOWN';
+};
+
+export type UsionErrorCode = keyof typeof ERROR_CODES;
+
+export declare class UsionError extends Error {
+  readonly name: 'UsionError';
+  readonly code: UsionErrorCode;
+  constructor(code: UsionErrorCode | string, message?: string);
+}
+
 declare const Usion: UsionSDK;
 
 export { Usion };