@usions/sdk 2.21.0 → 2.22.0

package/src/modules/wallet.js

@@ -21,13 +21,17 @@ export function createWalletModule(Usion) {
 
     /**
      * Get current wallet balance
+     * @param {object} [opts]
+     * @param {boolean} [opts.fresh] - Bypass the cache and re-query the host.
+     *   Use after out-of-band balance changes (e.g. a server-side settle).
      * @returns {Promise<number>} Balance in credits
      */
-    getBalance: function() {
+    getBalance: function(opts) {
       const self = this;
+      const fresh = !!(opts && opts.fresh);
 
       // If we have cached balance, return it
-      if (self._balance !== null) {
+      if (!fresh && self._balance !== null) {
         return Promise.resolve(self._balance);
       }
 
@@ -94,11 +98,14 @@ export function createWalletModule(Usion) {
           settled = true;
           cleanup();
           // Update cached balance from the authoritative new balance, else
-          // best-effort subtract (no-op if balance is unknown).
+          // best-effort subtract now and re-query the host so the cache
+          // converges on the real value (an estimate would otherwise stick
+          // until reload).
           if (response && response.newBalance !== undefined) {
             self._balance = response.newBalance;
-          } else if (self._balance !== null) {
-            self._balance -= amount;
+          } else {
+            if (self._balance !== null) self._balance -= amount;
+            self.getBalance({ fresh: true }).catch(function() { /* keep estimate */ });
           }
           resolve(response);
         }

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 {
@@ -901,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
@@ -946,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;
@@ -1064,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. */
@@ -1120,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';
 };
@@ -1139,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);
 }