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

package/src/realtime/multiplayer-forwarder.ts

@@ -1,28 +1,40 @@
-/**
- * `hub.mp`: invites, launches, the leave guard and own-server tickets,
- * forwarded to the social runtime.
- */
-import { getUiStack } from '../uistack/page-stack';
-import { pageBridge } from './bridge';
-import { hubLink } from './hub-link';
-import { latestState } from './latest-state';
-import type { HubMpApi } from './multiplayer-types';
-
-/** `hub.mp`: the multiplayer lifecycle. */
-export const multiplayerForwarder: HubMpApi = {
-  onLaunch: (listener) => pageBridge.subscribe((realtime) => realtime.mp.onLaunch(listener)),
-  onJoinInfo: (listener) => pageBridge.subscribe((realtime) => realtime.mp.onJoinInfo(listener)),
-  invite: (userId, options) => pageBridge.call((realtime) => realtime.mp.invite(userId, options)),
-  setBusy(isBusy, options) {
-    const busyOptions = options?.label === undefined ? {} : { label: options.label };
-    latestState.busy = { isBusy, options: busyOptions };
-    // The overlay stack is local, so "can't pause" works even without the runtime.
-    getUiStack().setCanPause(!isBusy);
-    pageBridge.current()?.mp.setBusy(isBusy, busyOptions);
-  },
-  // A direct request, not a runtime call: "Play online" must not depend on the
-  // social runtime having loaded (an old cached menu may never load it).
-  ticket: () => hubLink().getGameServerTicket(),
-  setJoinInfo: (partyId, joinInfo) => pageBridge.call((realtime) => realtime.mp.setJoinInfo(partyId, joinInfo)),
-  party: () => pageBridge.current()?.mp.party() ?? null,
-};
+/**
+ * `hub.mp`: invites, launches, the leave guard and own-server tickets,
+ * forwarded to the social runtime.
+ */
+import { getUiStack } from '../uistack/page-stack';
+import { outdatedRuntime, pageBridge } from './bridge';
+import { hubLink } from './hub-link';
+import { latestState } from './latest-state';
+import type { HubMpApi } from './multiplayer-types';
+
+/** `hub.mp`: the multiplayer lifecycle. */
+export const multiplayerForwarder: HubMpApi = {
+  onLaunch: (listener) => pageBridge.subscribe((realtime) => realtime.mp.onLaunch(listener)),
+  onJoinInfo: (listener) => pageBridge.subscribe((realtime) => realtime.mp.onJoinInfo(listener)),
+  invite: (userId, options) => pageBridge.call((realtime) => realtime.mp.invite(userId, options)),
+  setBusy(isBusy, options) {
+    const busyOptions = options?.label === undefined ? {} : { label: options.label };
+    latestState.busy = { isBusy, options: busyOptions };
+    // The overlay stack is local, so "can't pause" works even without the runtime.
+    getUiStack().setCanPause(!isBusy);
+    pageBridge.current()?.mp.setBusy(isBusy, busyOptions);
+  },
+  // A direct request, not a runtime call: "Play online" must not depend on the
+  // social runtime having loaded (an old cached menu may never load it).
+  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

@@ -1,52 +1,66 @@
-/**
- * The multiplayer lifecycle as games see it through `hub.mp`: invites,
- * launches, the leave guard and own-server tickets.
- */
-import type { Invite, JoinInfo, Launch, Party } from '@diffenderfer-games/hub-contract';
-
-/** `hub.mp.onJoinInfo` payload: the party leader published where to connect. */
-export interface JoinInfoEvent {
-  /** The party it is for. */
-  partyId: string;
-  /** Opaque connection details (a room code, a server address…). */
-  info: JoinInfo;
-}
-
-/** What `hub.mp.invite` resolves with. */
-export interface InviteResult {
-  /** The invite as sent. */
-  invite: Invite;
-}
-
-/** Options for `hub.mp.invite`. */
-export interface InviteOptions {
-  /** The game mode to invite to. */
-  mode?: string;
-}
-
-/** Options for `hub.mp.setBusy`. */
-export interface BusyOptions {
-  /** What the leave-confirmation calls the match ("a duel"). */
-  label?: string;
-}
-
-/** `hub.mp`: the multiplayer lifecycle (docs/multiplayer.md §7). */
-export interface HubMpApi {
-  /** 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). */
-  onJoinInfo(listener: (event: JoinInfoEvent) => void): () => void;
-  /** Invite a friend to this game. Rejects with `HubError` or `OfflineError`. */
-  invite(userId: number, options?: InviteOptions): Promise<InviteResult>;
-  /**
-   * A live match is in progress: the hub confirms before navigating away and
-   * overlay events carry `canPause: false`.
-   */
-  setBusy(isBusy: boolean, options?: BusyOptions): void;
-  /** A 60-second identity ticket for your own game server. */
-  ticket(): Promise<string>;
-  /** Host side, own-server games: tell the party where to connect. */
-  setJoinInfo(partyId: string, joinInfo: JoinInfo): Promise<void>;
-  /** My current party, or `null` (also `null` until the runtime is up). */
-  party(): Party | null;
-}
+/**
+ * The multiplayer lifecycle as games see it through `hub.mp`: invites,
+ * 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 {
+  /** The party it is for. */
+  partyId: string;
+  /** Opaque connection details (a room code, a server address…). */
+  info: JoinInfo;
+}
+
+/** What `hub.mp.invite` resolves with. */
+export interface InviteResult {
+  /** The invite as sent. */
+  invite: Invite;
+}
+
+/** Options for `hub.mp.invite`. */
+export interface InviteOptions {
+  /** The game mode to invite to. */
+  mode?: string;
+}
+
+/** Options for `hub.mp.setBusy`. */
+export interface BusyOptions {
+  /** What the leave-confirmation calls the match ("a duel"). */
+  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 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). */
+  onJoinInfo(listener: (event: JoinInfoEvent) => void): () => void;
+  /** Invite a friend to this game. Rejects with `HubError` or `OfflineError`. */
+  invite(userId: number, options?: InviteOptions): Promise<InviteResult>;
+  /**
+   * A live match is in progress: the hub confirms before navigating away and
+   * overlay events carry `canPause: false`.
+   */
+  setBusy(isBusy: boolean, options?: BusyOptions): void;
+  /** A 60-second identity ticket for your own game server. */
+  ticket(): Promise<string>;
+  /** Host side, own-server games: tell the party where to connect. */
+  setJoinInfo(partyId: string, joinInfo: JoinInfo): Promise<void>;
+  /** My current party, or `null` (also `null` until the runtime is up). */
+  party(): Party | null;
+}

package/src/realtime/page-runtime.ts

@@ -1,60 +1,60 @@
-/**
- * Finding the social runtime's realtime API on the page. The runtime owns the
- * `rt` singleton (plan §4.4): it registers on `window.__DG__.rt`, and older
- * runtimes only set the v1 name `window.__HUB_RT__`.
- */
-import { LEGACY_GLOBAL_NAMES } from '../globals';
-import { hasMethods, isObject, readField } from './cross-bundle';
-import type { RealtimeApi } from './runtime-api';
-import { REALTIME_SINGLETON_API } from './runtime-api';
-
-/** Whether `candidate` looks like a {@link RealtimeApi} (any bundle's). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the runtime is another bundle
-export function isRealtimeApi(candidate: unknown): candidate is RealtimeApi {
-  return typeof readField(candidate, 'version') === 'number'
-    && hasMethods(readField(candidate, 'presence'), ['set', 'clear'])
-    && hasMethods(readField(candidate, 'social'), ['openPlayer', 'friends', 'counts', 'chatMode', 'on'])
-    && hasMethods(readField(candidate, 'mp'), ['onLaunch', 'onJoinInfo', 'invite', 'setBusy', 'party'])
-    && hasMethods(readField(candidate, 'rooms'), ['create', 'join', 'list'])
-    && hasMethods(readField(candidate, 'notify'), ['setQuiet']);
-}
-
-let hasWarnedAboutApi = false;
-
-/** Warn once when the runtime registered a different shape number than this client knows. */
-function warnOnApiMismatch(registeredApi: number): void {
-  if (registeredApi === REALTIME_SINGLETON_API || hasWarnedAboutApi) {
-    return;
-  }
-  hasWarnedAboutApi = true;
-  // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
-  console.warn(`[hub] this page's social runtime speaks realtime api ${String(registeredApi)}, this client api ${String(REALTIME_SINGLETON_API)}. Fix: npm update @diffenderfer-games/hub`);
-}
-
-/** The page's realtime API if the runtime has loaded, else `null`. */
-export function findRealtimeApi(): RealtimeApi | null {
-  if (typeof window === 'undefined') {
-    return null;
-  }
-  const registered = window.__DG__?.rt;
-  if (registered !== undefined && isRealtimeApi(registered.instance)) {
-    warnOnApiMismatch(registered.api);
-    return registered.instance;
-  }
-  const legacy = window[LEGACY_GLOBAL_NAMES.rt];
-  return isRealtimeApi(legacy) ? legacy : null;
-}
-
-/** Whether the hub injected this page (`window.__HUB__`); without it the runtime can never arrive. */
-export function isHubInjectedPage(): boolean {
-  return typeof window !== 'undefined' && isObject(readField(window, '__HUB__'));
-}
-
-/** Why the social runtime failed to load on this page (set by the menu), or `''`. */
-export function readRuntimeFailure(): string {
-  if (typeof window === 'undefined') {
-    return '';
-  }
-  const failure = readField(window, '__HUB_RT_ERROR__');
-  return typeof failure === 'string' ? failure.slice(0, 120) : '';
-}
+/**
+ * Finding the social runtime's realtime API on the page. The runtime owns the
+ * `rt` singleton (plan §4.4): it registers on `window.__DG__.rt`, and older
+ * runtimes only set the v1 name `window.__HUB_RT__`.
+ */
+import { LEGACY_GLOBAL_NAMES } from '../globals';
+import { hasMethods, isObject, readField } from './cross-bundle';
+import type { RealtimeApi } from './runtime-api';
+import { REALTIME_SINGLETON_API } from './runtime-api';
+
+/** Whether `candidate` looks like a {@link RealtimeApi} (any bundle's). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the runtime is another bundle
+export function isRealtimeApi(candidate: unknown): candidate is RealtimeApi {
+  return typeof readField(candidate, 'version') === 'number'
+    && hasMethods(readField(candidate, 'presence'), ['set', 'clear'])
+    && hasMethods(readField(candidate, 'social'), ['openPlayer', 'friends', 'counts', 'chatMode', 'on'])
+    && hasMethods(readField(candidate, 'mp'), ['onLaunch', 'onJoinInfo', 'invite', 'setBusy', 'party'])
+    && hasMethods(readField(candidate, 'rooms'), ['create', 'join', 'list'])
+    && hasMethods(readField(candidate, 'notify'), ['setQuiet']);
+}
+
+let hasWarnedAboutApi = false;
+
+/** Warn once when the runtime registered a different shape number than this client knows. */
+function warnOnApiMismatch(registeredApi: number): void {
+  if (registeredApi === REALTIME_SINGLETON_API || hasWarnedAboutApi) {
+    return;
+  }
+  hasWarnedAboutApi = true;
+  // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
+  console.warn(`[hub] this page's social runtime speaks realtime api ${String(registeredApi)}, this client api ${String(REALTIME_SINGLETON_API)}. Fix: npm update @diffenderfer-games/hub`);
+}
+
+/** The page's realtime API if the runtime has loaded, else `null`. */
+export function findRealtimeApi(): RealtimeApi | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  const registered = window.__DG__?.rt;
+  if (registered !== undefined && isRealtimeApi(registered.instance)) {
+    warnOnApiMismatch(registered.api);
+    return registered.instance;
+  }
+  const legacy = window[LEGACY_GLOBAL_NAMES.rt];
+  return isRealtimeApi(legacy) ? legacy : null;
+}
+
+/** Whether the hub injected this page (`window.__HUB__`); without it the runtime can never arrive. */
+export function isHubInjectedPage(): boolean {
+  return typeof window !== 'undefined' && isObject(readField(window, '__HUB__'));
+}
+
+/** Why the social runtime failed to load on this page (set by the menu), or `''`. */
+export function readRuntimeFailure(): string {
+  if (typeof window === 'undefined') {
+    return '';
+  }
+  const failure = readField(window, '__HUB_RT_ERROR__');
+  return typeof failure === 'string' ? failure.slice(0, 120) : '';
+}

package/src/realtime/race-forwarder.ts

@@ -1,59 +1,59 @@
-/**
- * `hub.race`: races, forwarded to the social runtime. An old cached runtime
- * (feature version 1) has no races, which reads as "not available" rather
- * than a crash.
- */
-import { pageBridge } from './bridge';
-import { hubLink } from './hub-link';
-import type { HubRaceApi, RaceDefinition } from './race-types';
-import type { RealtimeApi } from './runtime-api';
-import { createRuntimeOpener } from './runtime-opener';
-
-const openWithRuntime = createRuntimeOpener(pageBridge);
-
-let raceDefinition: RaceDefinition | null = null;
-pageBridge.onReady((realtime) => {
-  if (raceDefinition !== null) {
-    realtime.race?.define(raceDefinition);
-  }
-});
-
-/** The runtime's race section, or an `OfflineError` for a runtime too old to race. */
-function requireRaces(realtime: RealtimeApi): HubRaceApi {
-  if (realtime.race === undefined) {
-    throw hubLink().createOfflineError('Races need the latest hub — reload the page.');
-  }
-  return realtime.race;
-}
-
-/** `hub.race`: races. */
-export const raceForwarder: HubRaceApi = {
-  define(definition) {
-    raceDefinition = definition;
-    pageBridge.current()?.race?.define(definition);
-  },
-  create: (options) => pageBridge.call((realtime) => requireRaces(realtime).create(options)),
-  join: (code, options) => pageBridge.call((realtime) => requireRaces(realtime).join(code, options)),
-  list: () => pageBridge.call((realtime) => requireRaces(realtime).list()),
-  browse: () => {
-    openWithRuntime((realtime) => {
-      realtime.race?.browse();
-    });
-  },
-  openHistory: (options) => {
-    openWithRuntime((realtime) => {
-      realtime.race?.openHistory(options);
-    });
-  },
-  history: (query) => pageBridge.call((realtime) => requireRaces(realtime).history(query)),
-  status: (stats, progress) => {
-    pageBridge.current()?.race?.status(stats, progress);
-  },
-  finish: (stats) => pageBridge.call((realtime) => requireRaces(realtime).finish(stats)),
-  lose: (stats) => pageBridge.call((realtime) => requireRaces(realtime).lose(stats)),
-  forfeit: () => pageBridge.call((realtime) => requireRaces(realtime).forfeit()),
-  leave: () => pageBridge.call((realtime) => requireRaces(realtime).leave()),
-  rematch: (params) => pageBridge.call((realtime) => requireRaces(realtime).rematch(params)),
-  current: () => pageBridge.current()?.race?.current() ?? null,
-  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.race?.on(event, listener) ?? (() => undefined)),
-};
+/**
+ * `hub.race`: races, forwarded to the social runtime. An old cached runtime
+ * (feature version 1) has no races, which reads as "not available" rather
+ * than a crash.
+ */
+import { pageBridge } from './bridge';
+import { hubLink } from './hub-link';
+import type { HubRaceApi, RaceDefinition } from './race-types';
+import type { RealtimeApi } from './runtime-api';
+import { createRuntimeOpener } from './runtime-opener';
+
+const openWithRuntime = createRuntimeOpener(pageBridge);
+
+let raceDefinition: RaceDefinition | null = null;
+pageBridge.onReady((realtime) => {
+  if (raceDefinition !== null) {
+    realtime.race?.define(raceDefinition);
+  }
+});
+
+/** The runtime's race section, or an `OfflineError` for a runtime too old to race. */
+function requireRaces(realtime: RealtimeApi): HubRaceApi {
+  if (realtime.race === undefined) {
+    throw hubLink().createOfflineError('Races need the latest hub — reload the page.');
+  }
+  return realtime.race;
+}
+
+/** `hub.race`: races. */
+export const raceForwarder: HubRaceApi = {
+  define(definition) {
+    raceDefinition = definition;
+    pageBridge.current()?.race?.define(definition);
+  },
+  create: (options) => pageBridge.call((realtime) => requireRaces(realtime).create(options)),
+  join: (code, options) => pageBridge.call((realtime) => requireRaces(realtime).join(code, options)),
+  list: () => pageBridge.call((realtime) => requireRaces(realtime).list()),
+  browse: () => {
+    openWithRuntime((realtime) => {
+      realtime.race?.browse();
+    });
+  },
+  openHistory: (options) => {
+    openWithRuntime((realtime) => {
+      realtime.race?.openHistory(options);
+    });
+  },
+  history: (query) => pageBridge.call((realtime) => requireRaces(realtime).history(query)),
+  status: (stats, progress) => {
+    pageBridge.current()?.race?.status(stats, progress);
+  },
+  finish: (stats) => pageBridge.call((realtime) => requireRaces(realtime).finish(stats)),
+  lose: (stats) => pageBridge.call((realtime) => requireRaces(realtime).lose(stats)),
+  forfeit: () => pageBridge.call((realtime) => requireRaces(realtime).forfeit()),
+  leave: () => pageBridge.call((realtime) => requireRaces(realtime).leave()),
+  rematch: (params) => pageBridge.call((realtime) => requireRaces(realtime).rematch(params)),
+  current: () => pageBridge.current()?.race?.current() ?? null,
+  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.race?.on(event, listener) ?? (() => undefined)),
+};