@usions/sdk 2.20.2 → 2.22.0

package/types/index.d.ts

@@ -97,7 +97,8 @@ export interface FileStorageModule {
 // ─── Wallet ──────────────────────────────────────────────────────
 
 export interface WalletModule {
-  getBalance(): Promise<number>;
+  /** Cached after the first call; pass `{ fresh: true }` to re-query the host. */
+  getBalance(opts?: { fresh?: boolean }): Promise<number>;
   hasCredits(amount: number): Promise<boolean>;
   requestPayment(amount: number, reason: string, data?: PaymentOptions): Promise<PaymentResponse>;
   onBalanceChange(callback: (balance: number) => void): UnsubscribeFn;
@@ -185,6 +186,9 @@ export interface PlayerJoinedData {
 export interface PlayerLeftData {
   room_id: string;
   player_id: string;
+  /** Authoritative roster (mirrors PlayerJoinedData) — reconcile membership from either event. */
+  player_ids: string[];
+  reason?: string;
 }
 
 export interface StateUpdateData {
@@ -274,6 +278,60 @@ export interface GameInviteResult {
   invited: string[];
 }
 
+/** Unified connection-state machine, identical across all transports. */
+export type GameConnectionState = 'connected' | 'disconnected' | 'rejoining' | 'reconnected';
+
+/** Payload of game.onReconnected — fires once after a reconnect's resync. */
+export interface ReconnectedInfo {
+  /** The server checkpoint from the resync (may be empty). */
+  state: Record<string, any> | null;
+  /** Highest action sequence after the resync. */
+  lastSequence: number;
+  /** True when recovery came through a game:sync payload. */
+  viaSync: boolean;
+}
+
+/** An action as seen by a syncedState reducer. */
+export interface SyncedStateAction {
+  playerId: string;
+  type: string;
+  data: any;
+  /** Authoritative sequence; undefined only for direct-mode local applies. */
+  sequence: number | undefined;
+}
+
+/** Options for game.syncedState(). */
+export interface SyncedStateOptions<S = Record<string, any>> {
+  /** Pure reducer applied to every action; default shallow-merges action.data. */
+  reduce?: (state: S, action: SyncedStateAction) => S;
+  /** Authority checkpoint cadence in actions (1 = every action; 0 disables). */
+  checkpointEvery?: number;
+  /** Who checkpoints: 'host' (player_ids[0], default) or 'all' participants. */
+  authority?: 'host' | 'all';
+  /** Default action type used by commit(data) (default 'update'). */
+  type?: string;
+}
+
+/** Reconnect-safe authoritative shared state (see game.syncedState). */
+export interface SyncedState<S = Record<string, any>> {
+  /** Current state value. */
+  get(): S;
+  /** Commit with the default action type. Applied exactly once via the echo. */
+  commit(data: Record<string, any>): Promise<ActionResult>;
+  /** Commit a named action; opts forwarded to game.action (nextTurn, …). */
+  commit(type: string, data?: Record<string, any>, opts?: GameActionOptions): Promise<ActionResult>;
+  /** Subscribe to changes: cb(state, reason). Returns an unsubscribe fn. */
+  onChange(callback: (state: S, reason: 'action' | 'recover') => void): UnsubscribeFn;
+  /** Whether this client is the checkpointing authority. */
+  isAuthority(): boolean;
+  /** Force a server checkpoint now (no-op result in direct mode). */
+  checkpoint(): Promise<{ success: boolean; error?: string; code?: UsionErrorCode }>;
+  /** Sequence of the last action applied into this state. */
+  getSequence(): number;
+  /** Detach all listeners; the instance stops receiving updates. */
+  destroy(): void;
+}
+
 export interface GameModule {
   // Connection
   connect(socketUrl?: string, token?: string): Promise<void>;
@@ -368,6 +426,36 @@ export interface GameModule {
    */
   onRoomAssigned(callback: (data: { roomId: string }) => void): UnsubscribeFn;
 
+  // ─── Reconnection lifecycle (SDK ≥ 2.21; documented since 2.16) ──────────
+  /** Highest action sequence seen (joins, syncs, live actions). */
+  getLastSequence(): number;
+  /** Highest action sequence applied locally; trails while catching up. */
+  getLastAppliedSequence(): number;
+  /** Current connection state, synchronously. */
+  getConnectionState(): GameConnectionState;
+  /**
+   * Observe connection-state transitions ('connected' → 'disconnected' →
+   * 'rejoining' → 'reconnected' → 'connected') — identical across the socket,
+   * embedded-proxy, and direct transports. One hook to drive a
+   * "Reconnecting…" overlay and gate input.
+   */
+  onConnectionState(callback: (state: GameConnectionState) => void): UnsubscribeFn;
+  /**
+   * Fires once per reconnect, after the resync completes. Restore local
+   * state here — it does NOT fire for a manually-requested sync.
+   */
+  onReconnected(callback: (info: ReconnectedInfo) => void): UnsubscribeFn;
+  /**
+   * Reconnect-safe authoritative shared state. Commits are sequenced actions
+   * applied through `reduce` on every client in the same order (deduped by
+   * sequence); the authority (player_ids[0] by default) auto-checkpoints via
+   * setState, and (re)joining clients recover automatically (load checkpoint,
+   * replay the un-checkpointed tail). Use for state that must survive a
+   * disconnect — unlike replicate() (realtime, lossy). Degrades to
+   * local-apply in direct mode (no platform checkpoint there).
+   */
+  syncedState<S = Record<string, any>>(initial: S, opts?: SyncedStateOptions<S>): SyncedState<S>;
+
   /**
    * Register an ADDITIONAL event listener. Unlike the onX methods this
    * supports multiple listeners per event, can be called before connect(),
@@ -817,7 +905,15 @@ export interface UsionSDK {
   config: UsionConfig;
 
   // Lifecycle
-  init(callback: (config: UsionConfig) => void): void;
+  /**
+   * Initialize the SDK. The callback fires when the host's INIT config
+   * arrives; every call also returns a Promise of the same config, so
+   * `const config = await Usion.init()` works. `opts.timeout` (ms) rejects
+   * the promise with UsionError(INIT_TIMEOUT) when no INIT arrives in time
+   * (embedded but host silent). (promise/timeout: SDK ≥ 2.22)
+   */
+  init(callback?: (config: UsionConfig) => void, opts?: { timeout?: number }): Promise<UsionConfig>;
+  init(opts: { timeout?: number }): Promise<UsionConfig>;
   exit(options?: { backCount?: number }): void;
 
   // Theme & Locale
@@ -862,8 +958,8 @@ export interface UsionSDK {
   // Logging
   log(msg: string): void;
 
-  // Generic event listener
-  on(type: string, callback: (data: any) => void): void;
+  // Generic event listener (returns an unsubscribe function)
+  on(type: string, callback: (data: any) => void): UnsubscribeFn;
 
   // UI helpers
   setLoading(btn: HTMLElement | string, loading: boolean): void;
@@ -980,8 +1076,14 @@ export interface CloudModule extends CloudScope {
 export interface Match { roomId: string; players: string[]; serviceId?: string; }
 
 export interface MatchmakingModule {
-  /** Join the quick-match queue; resolves when paired with online strangers. */
-  find(serviceId?: string, opts?: { size?: number }): Promise<Match>;
+  /**
+   * Join the quick-match queue; resolves when paired with online strangers.
+   * `opts.timeout` (ms) bounds the wait: on expiry the queue is left and the
+   * promise rejects with UsionError(MATCH_TIMEOUT). A newer find() rejects
+   * the previous one with SUPERSEDED; cancel() rejects it with CANCELLED.
+   * (timeout: SDK ≥ 2.22)
+   */
+  find(serviceId?: string, opts?: { size?: number; timeout?: number }): Promise<Match>;
   /** Leave the queue / stop waiting. */
   cancel(): Promise<any>;
   /** Called whenever a match is found. */
@@ -1036,16 +1138,29 @@ export declare const ERROR_CODES: {
   readonly NO_ROOM: 'NO_ROOM';
   readonly ROOM_NOT_FOUND: 'ROOM_NOT_FOUND';
   readonly NOT_PARTICIPANT: 'NOT_PARTICIPANT';
+  readonly NOT_IN_ROOM: 'NOT_IN_ROOM';
   readonly NOT_AUTHORITY: 'NOT_AUTHORITY';
   readonly NOT_AUTHENTICATED: 'NOT_AUTHENTICATED';
   readonly JOIN_TIMEOUT: 'JOIN_TIMEOUT';
   readonly CONNECT_TIMEOUT: 'CONNECT_TIMEOUT';
+  readonly INIT_TIMEOUT: 'INIT_TIMEOUT';
+  readonly MATCH_TIMEOUT: 'MATCH_TIMEOUT';
   readonly STATE_TOO_LARGE: 'STATE_TOO_LARGE';
   readonly INVALID_STATE: 'INVALID_STATE';
+  readonly STALE_STATE: 'STALE_STATE';
   readonly INVALID_NEXT_TURN: 'INVALID_NEXT_TURN';
+  readonly INVALID_INPUT: 'INVALID_INPUT';
+  readonly NOT_FOUND: 'NOT_FOUND';
+  readonly QUOTA_EXCEEDED: 'QUOTA_EXCEEDED';
+  readonly VALUE_TOO_LARGE: 'VALUE_TOO_LARGE';
+  readonly LOBBY_FULL: 'LOBBY_FULL';
+  readonly LOBBY_CLOSED: 'LOBBY_CLOSED';
+  readonly CONFLICT: 'CONFLICT';
   readonly RATE_LIMITED: 'RATE_LIMITED';
   readonly REQUEST_TIMEOUT: 'REQUEST_TIMEOUT';
   readonly QUEUE_FULL: 'QUEUE_FULL';
+  readonly CANCELLED: 'CANCELLED';
+  readonly SUPERSEDED: 'SUPERSEDED';
   readonly UNSUPPORTED: 'UNSUPPORTED';
   readonly UNKNOWN: 'UNKNOWN';
 };
@@ -1055,6 +1170,8 @@ export type UsionErrorCode = keyof typeof ERROR_CODES;
 export declare class UsionError extends Error {
   readonly name: 'UsionError';
   readonly code: UsionErrorCode;
+  /** Seconds until a RATE_LIMITED call may be retried (when the server sent it). */
+  readonly retryAfter?: number;
   constructor(code: UsionErrorCode | string, message?: string);
 }