@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.2

package/src/realtime/rooms-forwarder.ts

@@ -1,79 +1,91 @@
-/**
- * `hub.rooms`: hub relay rooms, forwarded to the social runtime. Each room is
- * wrapped so its rejections use the core client's error classes.
- */
-import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
-import { pageBridge, rethrowAsHubError } from './bridge';
-import type { HubRoom, HubRoomsApi, RoomEvents, RoomSelf, RoomSendOptions, RoomState, RoomStateOptions } from './room-types';
-
-/** A runtime room whose rejections are re-created as the core client's errors. */
-class ForwardedRoom implements HubRoom {
-  private readonly room: HubRoom;
-
-  constructor(room: HubRoom) {
-    this.room = room;
-  }
-
-  get info(): RoomInfo {
-    return this.room.info;
-  }
-
-  get state(): RoomState {
-    return this.room.state;
-  }
-
-  get me(): RoomSelf {
-    return this.room.me;
-  }
-
-  on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void {
-    return this.room.on(event, listener);
-  }
-
-  ready(isReady: boolean): Promise<void> {
-    return rethrowAsHubError(this.room.ready(isReady));
-  }
-
-  seat(seatData: Json): Promise<void> {
-    return rethrowAsHubError(this.room.seat(seatData));
-  }
-
-  start(): Promise<void> {
-    return rethrowAsHubError(this.room.start());
-  }
-
-  send(message: Json, options?: RoomSendOptions): Promise<void> {
-    return rethrowAsHubError(this.room.send(message, options));
-  }
-
-  setState(patch: RoomState, options?: RoomStateOptions): Promise<void> {
-    return rethrowAsHubError(this.room.setState(patch, options));
-  }
-
-  chat(text: string): Promise<string> {
-    return rethrowAsHubError(this.room.chat(text));
-  }
-
-  quick(phraseId: string): Promise<void> {
-    return rethrowAsHubError(this.room.quick(phraseId));
-  }
-
-  kick(userId: number): Promise<void> {
-    return rethrowAsHubError(this.room.kick(userId));
-  }
-
-  leave(): Promise<void> {
-    return rethrowAsHubError(this.room.leave());
-  }
-
-  end(results?: Json): Promise<void> {
-    return rethrowAsHubError(this.room.end(results));
-  }
-}
-
-/** `hub.rooms`: hub relay rooms. */
-export const roomsForwarder: HubRoomsApi = {
-  create: (options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.create(options))),
-  join: (codeOrId, options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.join(codeOrId, options))),
-  list: (options) => pageBridge.call((realtime) => realtime.rooms.list(options)),
-};
+/**
+ * `hub.rooms`: hub relay rooms, forwarded to the social runtime. Each room is
+ * wrapped so its rejections use the core client's error classes.
+ */
+import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
+import { outdatedRuntime, pageBridge, rethrowAsHubError } from './bridge';
+import type { HubRoom, HubRoomsApi, RoomEvents, RoomSelf, RoomSendOptions, RoomState, RoomStateOptions } from './room-types';
+import type { RoomSeat } from './wire-types';
+
+/** A runtime room whose rejections are re-created as the core client's errors. */
+class ForwardedRoom implements HubRoom {
+  private readonly room: HubRoom;
+
+  constructor(room: HubRoom) {
+    this.room = room;
+  }
+
+  get info(): RoomInfo {
+    return this.room.info;
+  }
+
+  get state(): RoomState {
+    return this.room.state;
+  }
+
+  get me(): RoomSelf {
+    return this.room.me;
+  }
+
+  seats(): RoomSeat[] {
+    return this.room.info.seats;
+  }
+
+  on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void {
+    return this.room.on(event, listener);
+  }
+
+  ready(isReady: boolean): Promise<void> {
+    return rethrowAsHubError(this.room.ready(isReady));
+  }
+
+  seat(seatData: Json): Promise<void> {
+    return rethrowAsHubError(this.room.seat(seatData));
+  }
+
+  start(): Promise<void> {
+    return rethrowAsHubError(this.room.start());
+  }
+
+  send(message: Json, options?: RoomSendOptions): Promise<void> {
+    return rethrowAsHubError(this.room.send(message, options));
+  }
+
+  setState(patch: RoomState, options?: RoomStateOptions): Promise<void> {
+    return rethrowAsHubError(this.room.setState(patch, options));
+  }
+
+  chat(text: string): Promise<string> {
+    return rethrowAsHubError(this.room.chat(text));
+  }
+
+  quick(phraseId: string): Promise<void> {
+    return rethrowAsHubError(this.room.quick(phraseId));
+  }
+
+  kick(userId: number): Promise<void> {
+    return rethrowAsHubError(this.room.kick(userId));
+  }
+
+  leave(): Promise<void> {
+    return rethrowAsHubError(this.room.leave());
+  }
+
+  end(results?: Json): Promise<void> {
+    return rethrowAsHubError(this.room.end(results));
+  }
+}
+
+/** `hub.rooms`: hub relay rooms. */
+export const roomsForwarder: HubRoomsApi = {
+  create: (options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.create(options))),
+  join: (codeOrId, options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.join(codeOrId, options))),
+  list: (options) => pageBridge.call((realtime) => realtime.rooms.list(options)),
+  reclaim: () => pageBridge.call(async (realtime) => {
+    if (realtime.rooms.reclaim === undefined) {
+      throw outdatedRuntime('Taking back a seat');
+    }
+    const held = await realtime.rooms.reclaim();
+    return held === null ? null : new ForwardedRoom(held);
+  }),
+};

package/src/realtime/runtime-api.ts

@@ -1,49 +1,60 @@
-/**
- * The realtime API the hub's social runtime (`/_hub/social.js`) installs on
- * the page, and that `hub.presence`, `hub.social`, `hub.mp`, `hub.rooms`,
- * `hub.notify` and `hub.race` forward to.
- */
-import type { HubMpApi } from './multiplayer-types';
-import type { HubRaceApi } from './race-types';
-import type { HubRoomsApi } from './room-types';
-import type { HubNotifyApi, HubPresenceApi, HubSocialApi } from './social-types';
-
-/**
- * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
- * 2 added races; a client feature-detects newer additions with it.
- */
-export const REALTIME_FEATURE_VERSION = 2;
-
-/**
- * The cross-bundle shape number of the `rt` page singleton (plan §4.4). The
- * runtime registers with it through `claimSingleton`; bump it only when the
- * shape of {@link RealtimeApi} changes incompatibly.
- */
-export const REALTIME_SINGLETON_API = 1;
-
-/** The window event the runtime fires once it has installed itself. */
-export const REALTIME_READY_EVENT = 'hub:rt-ready';
-
-/** The window event the menu fires when the runtime failed to load (its reason is on `window.__HUB_RT_ERROR__`). */
-export const REALTIME_FAILED_EVENT = 'hub:rt-failed';
-
-/**
- * Installed by the social runtime as the page's `rt` singleton (and the v1
- * alias `window.__HUB_RT__`).
- */
-export interface RealtimeApi {
-  /** The runtime's feature version (see {@link REALTIME_FEATURE_VERSION}). */
-  readonly version: number;
-  /** Presence reporting. */
-  presence: HubPresenceApi;
-  /** Friends and the social dialogs. */
-  social: HubSocialApi;
-  /** Invites, launches, the leave guard and tickets. */
-  mp: HubMpApi;
-  /** Hub relay rooms. */
-  rooms: HubRoomsApi;
-  /** Toast behaviour. */
-  notify: HubNotifyApi;
-  /** Races (feature version 2 and later). */
-  race?: HubRaceApi;
-}
+/**
+ * The realtime API the hub's social runtime (`/_hub/social.js`) installs on
+ * the page, and that `hub.presence`, `hub.social`, `hub.mp`, `hub.rooms`,
+ * `hub.notify` and `hub.race` forward to.
+ */
+import type { HubMpApi, InviteLinkMethods } from './multiplayer-types';
+import type { HubRaceApi } from './race-types';
+import type { HubRoomsApi, RoomReclaimMethods } from './room-types';
+import type { HubNotifyApi, HubPresenceApi, HubSocialApi, PlayOnlineMethods } from './social-types';
+
+/**
+ * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
+ * 2 added races; 3 added invite links and taking back a held seat; 4 added
+ * "Play online" (tournaments). A client feature-detects newer additions with
+ * it (or by the optional method).
+ */
+export const REALTIME_FEATURE_VERSION = 4;
+
+/** `hub.social` as a runtime installs it: version 4's `openPlayOnline` is missing on older runtimes. */
+export type RuntimeSocialApi = Omit<HubSocialApi, keyof PlayOnlineMethods> & Partial<PlayOnlineMethods>;
+
+/** `hub.mp` as a runtime installs it: version 3's invite-link methods are missing on older runtimes. */
+export type RuntimeMpApi = Omit<HubMpApi, keyof InviteLinkMethods> & Partial<InviteLinkMethods>;
+
+/** `hub.rooms` as a runtime installs it: version 3's `reclaim` is missing on older runtimes. */
+export type RuntimeRoomsApi = Omit<HubRoomsApi, keyof RoomReclaimMethods> & Partial<RoomReclaimMethods>;
+
+/**
+ * The cross-bundle shape number of the `rt` page singleton (plan §4.4). The
+ * runtime registers with it through `claimSingleton`; bump it only when the
+ * shape of {@link RealtimeApi} changes incompatibly.
+ */
+export const REALTIME_SINGLETON_API = 1;
+
+/** The window event the runtime fires once it has installed itself. */
+export const REALTIME_READY_EVENT = 'hub:rt-ready';
+
+/** The window event the menu fires when the runtime failed to load (its reason is on `window.__HUB_RT_ERROR__`). */
+export const REALTIME_FAILED_EVENT = 'hub:rt-failed';
+
+/**
+ * Installed by the social runtime as the page's `rt` singleton (and the v1
+ * alias `window.__HUB_RT__`).
+ */
+export interface RealtimeApi {
+  /** The runtime's feature version (see {@link REALTIME_FEATURE_VERSION}). */
+  readonly version: number;
+  /** Presence reporting. */
+  presence: HubPresenceApi;
+  /** Friends and the social dialogs. */
+  social: RuntimeSocialApi;
+  /** Invites, launches, the leave guard and tickets. */
+  mp: RuntimeMpApi;
+  /** Hub relay rooms. */
+  rooms: RuntimeRoomsApi;
+  /** Toast behaviour. */
+  notify: HubNotifyApi;
+  /** Races (feature version 2 and later). */
+  race?: HubRaceApi;
+}

package/src/realtime/runtime-opener.ts

@@ -1,61 +1,61 @@
-/**
- * Opening the runtime's UI (a player card, the friends drawer, the race
- * sheet) from a game button. A tap must never look dead: if the runtime isn't
- * there within a moment the player is told it is loading, and if it never
- * arrives, how to recover.
- */
-import type { RealtimeBridge } from './bridge';
-import { hideFallbackNotice, showFallbackNotice } from './fallback-notice';
-import { readRuntimeFailure } from './page-runtime';
-import type { RealtimeApi } from './runtime-api';
-import { REALTIME_FAILED_EVENT } from './runtime-api';
-
-/** How long before "still loading" shows. */
-const SLOW_NOTICE_MS = 1500;
-/** How long the failure notice stays up. */
-const FAILURE_NOTICE_MS = 8000;
-
-/** Tell the player the social runtime failed, with the reason the menu recorded. */
-function showRuntimeFailure(): void {
-  const reason = readRuntimeFailure();
-  showFallbackNotice(`Friends couldn't load${reason === '' ? '' : ` (${reason})`}. Reload the page to try again.`, FAILURE_NOTICE_MS);
-}
-
-/** Make an opener: runs a UI call on the runtime once it is up, with the loading and failure notices. */
-export function createRuntimeOpener(bridge: RealtimeBridge): (openUi: (realtime: RealtimeApi) => void) => void {
-  return (openUi) => {
-    const loaded = bridge.current();
-    if (loaded !== null) {
-      openUi(loaded);
-      return;
-    }
-    // The menu already knows the runtime failed.
-    if (readRuntimeFailure() !== '') {
-      showRuntimeFailure();
-      return;
-    }
-    const slowTimer = setTimeout(() => {
-      showFallbackNotice('Friends are still loading…');
-    }, SLOW_NOTICE_MS);
-    let isSettled = false;
-    const onFailed = (): void => {
-      if (!isSettled) {
-        isSettled = true;
-        clearTimeout(slowTimer);
-        showRuntimeFailure();
-      }
-    };
-    if (typeof window !== 'undefined') {
-      window.addEventListener(REALTIME_FAILED_EVENT, onFailed, { once: true });
-    }
-    bridge.whenReady().then((realtime) => {
-      if (isSettled) {
-        return;
-      }
-      isSettled = true;
-      clearTimeout(slowTimer);
-      hideFallbackNotice();
-      openUi(realtime);
-    }, onFailed);
-  };
-}
+/**
+ * Opening the runtime's UI (a player card, the friends drawer, the race
+ * sheet) from a game button. A tap must never look dead: if the runtime isn't
+ * there within a moment the player is told it is loading, and if it never
+ * arrives, how to recover.
+ */
+import type { RealtimeBridge } from './bridge';
+import { hideFallbackNotice, showFallbackNotice } from './fallback-notice';
+import { readRuntimeFailure } from './page-runtime';
+import type { RealtimeApi } from './runtime-api';
+import { REALTIME_FAILED_EVENT } from './runtime-api';
+
+/** How long before "still loading" shows. */
+const SLOW_NOTICE_MS = 1500;
+/** How long the failure notice stays up. */
+const FAILURE_NOTICE_MS = 8000;
+
+/** Tell the player the social runtime failed, with the reason the menu recorded. */
+function showRuntimeFailure(): void {
+  const reason = readRuntimeFailure();
+  showFallbackNotice(`Friends couldn't load${reason === '' ? '' : ` (${reason})`}. Reload the page to try again.`, FAILURE_NOTICE_MS);
+}
+
+/** Make an opener: runs a UI call on the runtime once it is up, with the loading and failure notices. */
+export function createRuntimeOpener(bridge: RealtimeBridge): (openUi: (realtime: RealtimeApi) => void) => void {
+  return (openUi) => {
+    const loaded = bridge.current();
+    if (loaded !== null) {
+      openUi(loaded);
+      return;
+    }
+    // The menu already knows the runtime failed.
+    if (readRuntimeFailure() !== '') {
+      showRuntimeFailure();
+      return;
+    }
+    const slowTimer = setTimeout(() => {
+      showFallbackNotice('Friends are still loading…');
+    }, SLOW_NOTICE_MS);
+    let isSettled = false;
+    const onFailed = (): void => {
+      if (!isSettled) {
+        isSettled = true;
+        clearTimeout(slowTimer);
+        showRuntimeFailure();
+      }
+    };
+    if (typeof window !== 'undefined') {
+      window.addEventListener(REALTIME_FAILED_EVENT, onFailed, { once: true });
+    }
+    bridge.whenReady().then((realtime) => {
+      if (isSettled) {
+        return;
+      }
+      isSettled = true;
+      clearTimeout(slowTimer);
+      hideFallbackNotice();
+      openUi(realtime);
+    }, onFailed);
+  };
+}

package/src/realtime/social-forwarder.ts

@@ -1,72 +1,77 @@
-/**
- * `hub.presence`, `hub.social` and `hub.notify`: thin forwarders to the
- * social runtime. Presence and quiet mode are "latest state" calls,
- * remembered and replayed when the runtime loads.
- */
-import { pageBridge } from './bridge';
-import { latestState } from './latest-state';
-import { createRuntimeOpener } from './runtime-opener';
-import type { HubNotifyApi, HubPresenceApi, HubSocialApi, SocialCounts } from './social-types';
-
-const openWithRuntime = createRuntimeOpener(pageBridge);
-
-/** Counts before the runtime is up. */
-const NO_COUNTS: SocialCounts = { online: 0, inGame: 0, friendsOnline: 0 };
-
-/** `hub.presence`: what you're doing, shown to friends. */
-export const presenceForwarder: HubPresenceApi = {
-  set(presence) {
-    latestState.presence = { ...presence };
-    pageBridge.current()?.presence.set(latestState.presence);
-  },
-  clear() {
-    latestState.presence = { kind: 'menu' };
-    pageBridge.current()?.presence.clear();
-  },
-};
-
-/** `hub.notify`: toast behaviour. */
-export const notifyForwarder: HubNotifyApi = {
-  setQuiet(isQuiet) {
-    latestState.isQuiet = isQuiet;
-    pageBridge.current()?.notify.setQuiet(isQuiet);
-  },
-};
-
-/** `hub.social`: friends and the hub's social dialogs. */
-export const socialForwarder: HubSocialApi = {
-  openPlayer: (ref) => {
-    openWithRuntime((realtime) => {
-      realtime.social.openPlayer(ref);
-    });
-  },
-  openFriends: () => {
-    openWithRuntime((realtime) => {
-      realtime.social.openFriends();
-    });
-  },
-  openChat: (userId) => {
-    openWithRuntime((realtime) => {
-      realtime.social.openChat(userId);
-    });
-  },
-  openInvite: (options) => {
-    openWithRuntime((realtime) => {
-      realtime.social.openInvite(options);
-    });
-  },
-  openSuggest: () => {
-    openWithRuntime((realtime) => {
-      realtime.social.openSuggest();
-    });
-  },
-  openNotify: (options) => {
-    openWithRuntime((realtime) => {
-      realtime.social.openNotify(options);
-    });
-  },
-  friends: () => pageBridge.call((realtime) => realtime.social.friends()),
-  counts: () => pageBridge.current()?.social.counts() ?? { ...NO_COUNTS },
-  chatMode: (userIds) => pageBridge.current()?.social.chatMode(userIds) ?? 'off',
-  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.social.on(event, listener)),
-};
+/**
+ * `hub.presence`, `hub.social` and `hub.notify`: thin forwarders to the
+ * social runtime. Presence and quiet mode are "latest state" calls,
+ * remembered and replayed when the runtime loads.
+ */
+import { pageBridge } from './bridge';
+import { latestState } from './latest-state';
+import { createRuntimeOpener } from './runtime-opener';
+import type { HubNotifyApi, HubPresenceApi, HubSocialApi, SocialCounts } from './social-types';
+
+const openWithRuntime = createRuntimeOpener(pageBridge);
+
+/** Counts before the runtime is up. */
+const NO_COUNTS: SocialCounts = { online: 0, inGame: 0, friendsOnline: 0 };
+
+/** `hub.presence`: what you're doing, shown to friends. */
+export const presenceForwarder: HubPresenceApi = {
+  set(presence) {
+    latestState.presence = { ...presence };
+    pageBridge.current()?.presence.set(latestState.presence);
+  },
+  clear() {
+    latestState.presence = { kind: 'menu' };
+    pageBridge.current()?.presence.clear();
+  },
+};
+
+/** `hub.notify`: toast behaviour. */
+export const notifyForwarder: HubNotifyApi = {
+  setQuiet(isQuiet) {
+    latestState.isQuiet = isQuiet;
+    pageBridge.current()?.notify.setQuiet(isQuiet);
+  },
+};
+
+/** `hub.social`: friends and the hub's social dialogs. */
+export const socialForwarder: HubSocialApi = {
+  openPlayer: (ref) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openPlayer(ref);
+    });
+  },
+  openFriends: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openFriends();
+    });
+  },
+  openChat: (userId) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openChat(userId);
+    });
+  },
+  openInvite: (options) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openInvite(options);
+    });
+  },
+  openSuggest: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openSuggest();
+    });
+  },
+  openNotify: (options) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openNotify(options);
+    });
+  },
+  openPlayOnline: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openPlayOnline?.();
+    });
+  },
+  friends: () => pageBridge.call((realtime) => realtime.social.friends()),
+  counts: () => pageBridge.current()?.social.counts() ?? { ...NO_COUNTS },
+  chatMode: (userIds) => pageBridge.current()?.social.chatMode(userIds) ?? 'off',
+  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.social.on(event, listener)),
+};