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

package/src/realtime/bridge.ts

@@ -117,5 +117,10 @@ export async function rethrowAsHubError<Result>(pending: Promise<Result>): Promi
   }
 }
 
+/** The rejection for a feature the page's social runtime is too old to have (version 3 additions). */
+export function outdatedRuntime(feature: string): Error {
+  return hubLink().createOfflineError(`${feature} needs the newest hub. Reload the page to update.`);
+}
+
 /** The page's one bridge (per client bundle). */
 export const pageBridge = new RealtimeBridge();

package/src/realtime/multiplayer-forwarder.ts

@@ -3,7 +3,7 @@
  * forwarded to the social runtime.
  */
 import { getUiStack } from '../uistack/page-stack';
-import { pageBridge } from './bridge';
+import { outdatedRuntime, pageBridge } from './bridge';
 import { hubLink } from './hub-link';
 import { latestState } from './latest-state';
 import type { HubMpApi } from './multiplayer-types';
@@ -25,4 +25,16 @@ export const multiplayerForwarder: HubMpApi = {
   ticket: () => hubLink().getGameServerTicket(),
   setJoinInfo: (partyId, joinInfo) => pageBridge.call((realtime) => realtime.mp.setJoinInfo(partyId, joinInfo)),
   party: () => pageBridge.current()?.mp.party() ?? null,
+  inviteLink: () => pageBridge.call((realtime) => {
+    if (realtime.mp.inviteLink === undefined) {
+      throw outdatedRuntime('Invite links');
+    }
+    return realtime.mp.inviteLink();
+  }),
+  revokeInviteLink: (token) => pageBridge.call((realtime) => {
+    if (realtime.mp.revokeInviteLink === undefined) {
+      throw outdatedRuntime('Invite links');
+    }
+    return realtime.mp.revokeInviteLink(token);
+  }),
 };

package/src/realtime/multiplayer-types.ts

@@ -3,6 +3,7 @@
  * launches, the leave guard and own-server tickets.
  */
 import type { Invite, JoinInfo, Launch, Party } from '@diffenderfer-games/hub-contract';
+import type { InviteLink } from './wire-types';
 
 /** `hub.mp.onJoinInfo` payload: the party leader published where to connect. */
 export interface JoinInfoEvent {
@@ -30,8 +31,21 @@ export interface BusyOptions {
   label?: string;
 }
 
+/** What feature version 3 added to `hub.mp`: invite links. */
+export interface InviteLinkMethods {
+  /**
+   * A shareable link to the room I'm in (my live one when it exists): anyone
+   * who opens it joins while a seat is free, otherwise watches. It expires
+   * after 24 h. Claimed accounts only; rejects with `HubError`
+   * (`not_in_room`, `too_many_links`, `rate_limited`) or `OfflineError`.
+   */
+  inviteLink(): Promise<InviteLink>;
+  /** Revoke a link I made, or one into a room I host. */
+  revokeInviteLink(token: string): Promise<void>;
+}
+
 /** `hub.mp`: the multiplayer lifecycle (docs/multiplayer.md §7). */
-export interface HubMpApi {
+export interface HubMpApi extends InviteLinkMethods {
   /** Invite, join and watch arrivals. Call at boot; launches that arrived earlier are buffered. */
   onLaunch(listener: (launch: Launch) => void): () => void;
   /** The party leader published join info (e.g. a room code). */

package/src/realtime/room-types.ts

@@ -3,7 +3,7 @@
  * multiplayer for static games, relayed (never refereed) by the hub.
  */
 import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
-import type { RoomChatLine, RoomMessage } from './wire-types';
+import type { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange } from './wire-types';
 
 /** The shared room state (a JSON object, at most 32 KB). */
 export type RoomState = Record<string, Json>;
@@ -20,6 +20,13 @@ export interface RoomCreateOptions {
   maxPlayers?: number;
   /** `host` (default): guests' unaddressed sends reach the host only. `relay`: everyone hears every send. */
   model?: 'host' | 'relay';
+  /**
+   * When the host role moves on mid-game: `grace` (default) once the host's
+   * seat is freed (left, or 3 minutes away), so a host holding hidden state
+   * can come back; `drop` as soon as the host drops, for games whose truth is
+   * all in `setState`.
+   */
+  hostMigration?: 'grace' | 'drop';
   /** Seat this party in the room. */
   partyId?: string;
 }
@@ -52,6 +59,13 @@ export interface RoomEvents {
   ended: { room: RoomInfo; results?: Json };
   /** A player left mid-game (or their reconnect grace ran out). */
   abandoned: { userId: number; reason?: string };
+  /**
+   * A seat changed: `away` (dropped; held until `graceEndsAt`, so hand it to
+   * your computer player), `back` (reclaimed: give control back) or `gone`
+   * (freed: left, kicked or the grace ran out). The game never ends on its
+   * own because of this; `info.hostId` may have moved to another player.
+   */
+  seat: RoomSeatChange;
 }
 
 /** Who I am in a room. */
@@ -84,6 +98,8 @@ export interface HubRoom {
   readonly state: RoomState;
   /** Who I am in this room. */
   readonly me: RoomSelf;
+  /** The seats as last reported; `connected: false` while a seat is away. */
+  seats(): RoomSeat[];
   /** Subscribe to a room event. Returns the unsubscribe function. */
   on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void;
   /** Mark my seat ready (or not). */
@@ -114,8 +130,18 @@ export interface RoomListOptions {
   mode?: string;
 }
 
+/** What feature version 3 added to `hub.rooms`. */
+export interface RoomReclaimMethods {
+  /**
+   * Take back the seat I still hold in this game (after a reload, from
+   * another tab): the room, or `null` when I hold none. The hub also does
+   * this on its own at boot, as a `join` launch with `via: 'rejoin'`.
+   */
+  reclaim(): Promise<HubRoom | null>;
+}
+
 /** `hub.rooms`: hub relay rooms (static games, no server). */
-export interface HubRoomsApi {
+export interface HubRoomsApi extends RoomReclaimMethods {
   /** Create a room and take its first seat. */
   create(options?: RoomCreateOptions): Promise<HubRoom>;
   /** Join a room by its 5-character code or its id. */

package/src/realtime/rooms-forwarder.ts

@@ -3,8 +3,9 @@
  * 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 { 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 {
@@ -26,6 +27,10 @@ class ForwardedRoom implements HubRoom {
     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);
   }
@@ -76,4 +81,11 @@ 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

@@ -3,16 +3,27 @@
  * 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 { HubMpApi, InviteLinkMethods } from './multiplayer-types';
 import type { HubRaceApi } from './race-types';
-import type { HubRoomsApi } from './room-types';
-import type { HubNotifyApi, HubPresenceApi, HubSocialApi } from './social-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; a client feature-detects newer additions with it.
+ * 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 = 2;
+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
@@ -37,11 +48,11 @@ export interface RealtimeApi {
   /** Presence reporting. */
   presence: HubPresenceApi;
   /** Friends and the social dialogs. */
-  social: HubSocialApi;
+  social: RuntimeSocialApi;
   /** Invites, launches, the leave guard and tickets. */
-  mp: HubMpApi;
+  mp: RuntimeMpApi;
   /** Hub relay rooms. */
-  rooms: HubRoomsApi;
+  rooms: RuntimeRoomsApi;
   /** Toast behaviour. */
   notify: HubNotifyApi;
   /** Races (feature version 2 and later). */

package/src/realtime/social-forwarder.ts

@@ -65,6 +65,11 @@ export const socialForwarder: HubSocialApi = {
       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',

package/src/realtime/social-types.ts

@@ -61,6 +61,11 @@ export interface HubSocialApi {
   openSuggest(): void;
   /** Open notification settings, optionally focused on a game's lobby bell. */
   openNotify(options?: { game?: string }): void;
+  /**
+   * Open "Play online": games waiting for a player, invites, tournaments and
+   * the quick 1v1 (feature version 4; a no-op on older runtimes).
+   */
+  openPlayOnline(): void;
   /** Friends with live presence. Rejects with `OfflineError` without the runtime. */
   friends(): Promise<FriendEntry[]>;
   /** Live counts; all zero until the runtime is up. */
@@ -71,6 +76,9 @@ export interface HubSocialApi {
   on<Name extends keyof SocialEvents>(event: Name, listener: (payload: SocialEvents[Name]) => void): () => void;
 }
 
+/** What feature version 4 added to `hub.social`. */
+export type PlayOnlineMethods = Pick<HubSocialApi, 'openPlayOnline'>;
+
 /** `hub.notify`: toast behaviour during intense play. */
 export interface HubNotifyApi {
   /** Quiet: toasts collapse into the menu badge; invites still show as a small pill. */

package/src/realtime/wire-types.ts

@@ -9,6 +9,7 @@ import type {
   OpAck,
   ops,
   InviteCreated as InviteCreatedSchema,
+  InviteLink as InviteLinkSchema,
   RaceHistory as RaceHistorySchema,
   RaceResultPlayer as RaceResultPlayerSchema,
   RaceRecordPlayer as RaceRecordPlayerSchema,
@@ -51,6 +52,12 @@ export type RoomMessage = ServerEvents['room.msg'];
 /** A shared-state change (`ev:room.state`); patches are shallow-merged unless `replace`. */
 export type RoomStateChange = ServerEvents['room.state'];
 
+/** A seat went away, came back or is gone (`ev:room.seat`). */
+export type RoomSeatChange = ServerEvents['room.seat'];
+
+/** A shareable invite link into a room (`POST /mp/links`). */
+export type InviteLink = SchemaOutput<typeof InviteLinkSchema>;
+
 /** A moderated room chat line (`ev:room.chat`). */
 export type RoomChatLine = ServerEvents['room.chat'];
 

package/src/rooms.ts

@@ -6,5 +6,5 @@
  */
 export { roomsForwarder as rooms } from './realtime/rooms-forwarder';
 export type * from './realtime/room-types';
-export type { RoomChatLine, RoomMessage, RoomSeat, RoomStateChange } from './realtime/wire-types';
+export type { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange, RoomStateChange } from './realtime/wire-types';
 export type { RoomInfo } from '@diffenderfer-games/hub-contract';