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

package/src/realtime/social-types.ts

@@ -1,78 +1,86 @@
-/**
- * Friends, presence and notification shapes as games see them through
- * `hub.social`, `hub.presence` and `hub.notify`.
- */
-import type { ChatMode, FriendEntry, Invite, Party, Presence, PresenceInput } from '@diffenderfer-games/hub-contract';
-
-/** Online counts as a game sees them. */
-export interface SocialCounts {
-  /** Everyone online on the site. */
-  online: number;
-  /** Players in the current game (0 on the catalog page). */
-  inGame: number;
-  /** My friends currently online. */
-  friendsOnline: number;
-}
-
-/** Events `hub.social.on` delivers, name → payload. */
-export interface SocialEvents {
-  /** The friends list changed. */
-  friends: FriendEntry[];
-  /** A friend's presence changed (`null` when they went offline). */
-  presence: { userId: number; p: Presence | null };
-  /** The online counts changed. */
-  counts: SocialCounts;
-  /** An invite arrived. */
-  invite: Invite;
-  /** My party changed (`null` when I left it). */
-  party: Party | null;
-}
-
-/** Who to open a player card for. */
-export type PlayerRef = { userId: number } | { username: string };
-
-/** Options for the invite picker. */
-export interface OpenInviteOptions {
-  /** Preselect this friend. */
-  userId?: number;
-  /** The game mode to invite to. */
-  mode?: string;
-}
-
-/** `hub.presence`: what you're doing, shown to friends (privacy is automatic). */
-export interface HubPresenceApi {
-  /** Report an activity, e.g. `{ kind: 'playing', detail: 'Level 3' }`. Coalesced; safe to call often. */
-  set(presence: PresenceInput): void;
-  /** Back to "in the menu". */
-  clear(): void;
-}
-
-/** `hub.social`: friends and the hub's social dialogs. */
-export interface HubSocialApi {
-  /** Open a player card (add friend, message, invite, block, report). */
-  openPlayer(ref: PlayerRef): void;
-  /** Open the hub menu on the Friends section. */
-  openFriends(): void;
-  /** Open the chat with a friend. */
-  openChat(userId: number): void;
-  /** Open the invite picker (current game by default). */
-  openInvite(options?: OpenInviteOptions): void;
-  /** Open the game-suggestion form and board. */
-  openSuggest(): void;
-  /** Open notification settings, optionally focused on a game's lobby bell. */
-  openNotify(options?: { game?: string }): void;
-  /** Friends with live presence. Rejects with `OfflineError` without the runtime. */
-  friends(): Promise<FriendEntry[]>;
-  /** Live counts; all zero until the runtime is up. */
-  counts(): SocialCounts;
-  /** The effective chat mode (with these players); `'off'` until the runtime is up. */
-  chatMode(userIds?: number[]): ChatMode;
-  /** Subscribe to social events; works before the runtime loads. Returns the unsubscribe function. */
-  on<Name extends keyof SocialEvents>(event: Name, listener: (payload: SocialEvents[Name]) => void): () => void;
-}
-
-/** `hub.notify`: toast behaviour during intense play. */
-export interface HubNotifyApi {
-  /** Quiet: toasts collapse into the menu badge; invites still show as a small pill. */
-  setQuiet(isQuiet: boolean): void;
-}
+/**
+ * Friends, presence and notification shapes as games see them through
+ * `hub.social`, `hub.presence` and `hub.notify`.
+ */
+import type { ChatMode, FriendEntry, Invite, Party, Presence, PresenceInput } from '@diffenderfer-games/hub-contract';
+
+/** Online counts as a game sees them. */
+export interface SocialCounts {
+  /** Everyone online on the site. */
+  online: number;
+  /** Players in the current game (0 on the catalog page). */
+  inGame: number;
+  /** My friends currently online. */
+  friendsOnline: number;
+}
+
+/** Events `hub.social.on` delivers, name → payload. */
+export interface SocialEvents {
+  /** The friends list changed. */
+  friends: FriendEntry[];
+  /** A friend's presence changed (`null` when they went offline). */
+  presence: { userId: number; p: Presence | null };
+  /** The online counts changed. */
+  counts: SocialCounts;
+  /** An invite arrived. */
+  invite: Invite;
+  /** My party changed (`null` when I left it). */
+  party: Party | null;
+}
+
+/** Who to open a player card for. */
+export type PlayerRef = { userId: number } | { username: string };
+
+/** Options for the invite picker. */
+export interface OpenInviteOptions {
+  /** Preselect this friend. */
+  userId?: number;
+  /** The game mode to invite to. */
+  mode?: string;
+}
+
+/** `hub.presence`: what you're doing, shown to friends (privacy is automatic). */
+export interface HubPresenceApi {
+  /** Report an activity, e.g. `{ kind: 'playing', detail: 'Level 3' }`. Coalesced; safe to call often. */
+  set(presence: PresenceInput): void;
+  /** Back to "in the menu". */
+  clear(): void;
+}
+
+/** `hub.social`: friends and the hub's social dialogs. */
+export interface HubSocialApi {
+  /** Open a player card (add friend, message, invite, block, report). */
+  openPlayer(ref: PlayerRef): void;
+  /** Open the hub menu on the Friends section. */
+  openFriends(): void;
+  /** Open the chat with a friend. */
+  openChat(userId: number): void;
+  /** Open the invite picker (current game by default). */
+  openInvite(options?: OpenInviteOptions): void;
+  /** Open the game-suggestion form and board. */
+  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. */
+  counts(): SocialCounts;
+  /** The effective chat mode (with these players); `'off'` until the runtime is up. */
+  chatMode(userIds?: number[]): ChatMode;
+  /** Subscribe to social events; works before the runtime loads. Returns the unsubscribe function. */
+  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. */
+  setQuiet(isQuiet: boolean): void;
+}

package/src/realtime/types.ts

@@ -1,53 +1,54 @@
-/**
- * Every public realtime type in one place: the realtime API the social
- * runtime implements, the shapes `hub.social`, `hub.mp`, `hub.rooms` and
- * `hub.race` use, and the contract entities they carry. Types only.
- */
-export type {
-  Audience,
-  ChatMode,
-  Conversation,
-  Counts,
-  ErrorBody,
-  FriendEntry,
-  Invite,
-  JoinInfo,
-  Launch,
-  LaunchTicket,
-  Message,
-  MessagesPage,
-  NotifyChange,
-  NotifyPrefs,
-  Party,
-  PlayerCard,
-  PlayerLite,
-  Presence,
-  PresenceInput,
-  PresenceKind,
-  RaceOutcome,
-  RaceParams,
-  RaceRecord,
-  RaceResult,
-  RaceState,
-  RaceStats,
-  RaceStatValue,
-  Racer,
-  RacerResult,
-  RacerState,
-  RecentPlayer,
-  Relation,
-  ReportInput,
-  ReportKind,
-  ReportReason,
-  RoomInfo,
-  SocialConfig,
-  SocialMe,
-  Suggestion,
-  SuggestionStatus,
-} from '@diffenderfer-games/hub-contract';
-export type * from './wire-types';
-export type * from './social-types';
-export type * from './multiplayer-types';
-export type * from './room-types';
-export type * from './race-types';
-export type { RealtimeApi } from './runtime-api';
+/**
+ * Every public realtime type in one place: the realtime API the social
+ * runtime implements, the shapes `hub.social`, `hub.mp`, `hub.rooms` and
+ * `hub.race` use, and the contract entities they carry. Types only.
+ */
+export type {
+  Audience,
+  ChatMode,
+  Conversation,
+  Counts,
+  ErrorBody,
+  FriendEntry,
+  Invite,
+  JoinInfo,
+  Launch,
+  LaunchTicket,
+  Message,
+  MessagesPage,
+  NotifyChange,
+  NotifyPrefs,
+  Party,
+  PlayerCard,
+  PlayerLite,
+  Presence,
+  PresenceInput,
+  PresenceKind,
+  RaceOutcome,
+  RaceParams,
+  RaceRecord,
+  RaceResult,
+  RaceState,
+  RaceStats,
+  RaceStatValue,
+  Racer,
+  RacerResult,
+  RacerState,
+  RecentPlayer,
+  Relation,
+  ReportInput,
+  ReportKind,
+  ReportReason,
+  RoomInfo,
+  SocialConfig,
+  SocialMe,
+  Suggestion,
+  SuggestionStatus,
+} from '@diffenderfer-games/hub-contract';
+export type * from './wire-types';
+export type * from './social-types';
+export type * from './multiplayer-types';
+export type * from './room-types';
+export type * from './race-types';
+export type { RealtimeApi } from './runtime-api';
+export type { RuntimeWorldApi, WorldEventName, WorldOpName } from './world-types';

package/src/realtime/wire-types.ts

@@ -1,72 +1,79 @@
-/**
- * The `/_ws` wire shapes the realtime runtime and the forwarders share,
- * derived from the hub contract so they can never drift from what the server
- * sends. Types only: nothing here costs a byte at runtime.
- */
-import type {
-  EventData,
-  events,
-  OpAck,
-  ops,
-  InviteCreated as InviteCreatedSchema,
-  RaceHistory as RaceHistorySchema,
-  RaceResultPlayer as RaceResultPlayerSchema,
-  RaceRecordPlayer as RaceRecordPlayerSchema,
-  RoomSeat as RoomSeatSchema,
-} from '@diffenderfer-games/hub-contract';
-
-/** The parsed (output) type of a contract schema, without importing zod. */
-export type SchemaOutput<Schema> = Schema extends { readonly _zod: { readonly output: infer Output } } ? Output : never;
-
-/** Every server event, name → payload (the contract's `events`). */
-export type ServerEvents = { [Name in keyof typeof events]: EventData<(typeof events)[Name]> };
-
-/** The `hello` ack: everything the Friends drawer needs in one round-trip. */
-export type Snapshot = OpAck<(typeof ops)['hello']>;
-
-/** A generic server notice rendered as a toast (`ev:notice`). */
-export type Notice = ServerEvents['notice'];
-
-/** A seat in a hub room. */
-export type RoomSeat = SchemaOutput<typeof RoomSeatSchema>;
-
-/** One racer's line in a decided race. */
-export type RaceResultPlayer = SchemaOutput<typeof RaceResultPlayerSchema>;
-
-/** A racer in a history record. Suspended opponents are `hidden` (id 0, no name). */
-export type RaceRecordPlayer = SchemaOutput<typeof RaceRecordPlayerSchema>;
-
-/** A page of the player's races, newest first (`GET /race/history`). */
-export type RaceHistory = SchemaOutput<typeof RaceHistorySchema>;
-
-/** `POST /mp/invites`: the invite plus the inviter's own launch. */
-export type InviteCreated = SchemaOutput<typeof InviteCreatedSchema>;
-
-/** A live status line from another racer (`ev:race.status`); `at` is ms since the go on the server clock. */
-export type RaceStatusEvent = ServerEvents['race.status'];
-
-/** A relayed game message (`ev:room.msg`). */
-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 moderated room chat line (`ev:room.chat`). */
-export type RoomChatLine = ServerEvents['room.chat'];
-
-/**
- * What a rejected realtime call throws. The runtime is another bundle, so its
- * errors are re-created as the game's own `HubError` classes by the forwarders.
- */
-export interface RealtimeErrorShape extends Error {
-  /** HTTP status (REST), absent for transport and socket errors. */
-  status?: number;
-  /** The machine-readable code from the error body. */
-  code?: string;
-  /** Why content was rejected. */
-  reason?: string;
-  /** A player-facing hint. */
-  hint?: string;
-  /** How long to wait before retrying, when rate limited. */
-  retryAfterMs?: number;
-}
+/**
+ * The `/_ws` wire shapes the realtime runtime and the forwarders share,
+ * derived from the hub contract so they can never drift from what the server
+ * sends. Types only: nothing here costs a byte at runtime.
+ */
+import type {
+  EventData,
+  events,
+  OpAck,
+  ops,
+  InviteCreated as InviteCreatedSchema,
+  InviteLink as InviteLinkSchema,
+  RaceHistory as RaceHistorySchema,
+  RaceResultPlayer as RaceResultPlayerSchema,
+  RaceRecordPlayer as RaceRecordPlayerSchema,
+  RoomSeat as RoomSeatSchema,
+} from '@diffenderfer-games/hub-contract';
+
+/** The parsed (output) type of a contract schema, without importing zod. */
+export type SchemaOutput<Schema> = Schema extends { readonly _zod: { readonly output: infer Output } } ? Output : never;
+
+/** Every server event, name → payload (the contract's `events`). */
+export type ServerEvents = { [Name in keyof typeof events]: EventData<(typeof events)[Name]> };
+
+/** The `hello` ack: everything the Friends drawer needs in one round-trip. */
+export type Snapshot = OpAck<(typeof ops)['hello']>;
+
+/** A generic server notice rendered as a toast (`ev:notice`). */
+export type Notice = ServerEvents['notice'];
+
+/** A seat in a hub room. */
+export type RoomSeat = SchemaOutput<typeof RoomSeatSchema>;
+
+/** One racer's line in a decided race. */
+export type RaceResultPlayer = SchemaOutput<typeof RaceResultPlayerSchema>;
+
+/** A racer in a history record. Suspended opponents are `hidden` (id 0, no name). */
+export type RaceRecordPlayer = SchemaOutput<typeof RaceRecordPlayerSchema>;
+
+/** A page of the player's races, newest first (`GET /race/history`). */
+export type RaceHistory = SchemaOutput<typeof RaceHistorySchema>;
+
+/** `POST /mp/invites`: the invite plus the inviter's own launch. */
+export type InviteCreated = SchemaOutput<typeof InviteCreatedSchema>;
+
+/** A live status line from another racer (`ev:race.status`); `at` is ms since the go on the server clock. */
+export type RaceStatusEvent = ServerEvents['race.status'];
+
+/** A relayed game message (`ev:room.msg`). */
+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'];
+
+/**
+ * What a rejected realtime call throws. The runtime is another bundle, so its
+ * errors are re-created as the game's own `HubError` classes by the forwarders.
+ */
+export interface RealtimeErrorShape extends Error {
+  /** HTTP status (REST), absent for transport and socket errors. */
+  status?: number;
+  /** The machine-readable code from the error body. */
+  code?: string;
+  /** Why content was rejected. */
+  reason?: string;
+  /** A player-facing hint. */
+  hint?: string;
+  /** How long to wait before retrying, when rate limited. */
+  retryAfterMs?: number;
+}

package/src/realtime/world-types.ts

@@ -0,0 +1,20 @@
+/**
+ * The world over the runtime's socket (docs/plans/world.md §8.3): the
+ * `world.*` ops and events, typed from the contract. The hub's world client
+ * calls it; games don't need it.
+ */
+import type { EventData, EventName, events, OpAck, OpInput, OpName, ops } from '@diffenderfer-games/hub-contract';
+
+/** A `world.*` op name. */
+export type WorldOpName = Extract<OpName, `world.${string}`>;
+
+/** A `world.*` event name. */
+export type WorldEventName = Extract<EventName, `world.${string}`>;
+
+/** `rt.world` (realtime feature version 6 and later). */
+export interface RuntimeWorldApi {
+  /** Send a world op on the page's socket; rejects with the hub's refusal. */
+  op<Name extends WorldOpName>(name: Name, input: OpInput<(typeof ops)[Name]>): Promise<OpAck<(typeof ops)[Name]>>;
+  /** Hear a world event; returns the unsubscribe. */
+  on<Name extends WorldEventName>(name: Name, listener: (payload: EventData<(typeof events)[Name]>) => void): () => void;
+}

package/src/rooms.ts

@@ -1,10 +1,10 @@
-/**
- * `@diffenderfer-games/hub/rooms`: the hub relay rooms forwarder (`hub.rooms`),
- * for games that want only this namespace.
- *
- * @packageDocumentation
- */
-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 { RoomInfo } from '@diffenderfer-games/hub-contract';
+/**
+ * `@diffenderfer-games/hub/rooms`: the hub relay rooms forwarder (`hub.rooms`),
+ * for games that want only this namespace.
+ *
+ * @packageDocumentation
+ */
+export { roomsForwarder as rooms } from './realtime/rooms-forwarder';
+export type * from './realtime/room-types';
+export type { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange, RoomStateChange } from './realtime/wire-types';
+export type { RoomInfo } from '@diffenderfer-games/hub-contract';

package/src/social.ts

@@ -1,18 +1,19 @@
-/**
- * `@diffenderfer-games/hub/social`: the social forwarders (`hub.social`,
- * `hub.presence`, `hub.notify`), and every realtime type: the API the hub's
- * social runtime implements and the shapes it carries.
- *
- * @packageDocumentation
- */
-export { notifyForwarder as notify, presenceForwarder as presence, socialForwarder as social } from './realtime/social-forwarder';
-export { linkRealtimeToHub } from './realtime/hub-link';
-export type { RealtimeHubLink } from './realtime/hub-link';
-export { findRealtimeApi, isRealtimeApi } from './realtime/page-runtime';
-export {
-  REALTIME_FAILED_EVENT,
-  REALTIME_FEATURE_VERSION,
-  REALTIME_READY_EVENT,
-  REALTIME_SINGLETON_API,
-} from './realtime/runtime-api';
-export type * from './realtime/types';
+/**
+ * `@diffenderfer-games/hub/social`: the social forwarders (`hub.social`,
+ * `hub.presence`, `hub.notify`), and every realtime type: the API the hub's
+ * social runtime implements and the shapes it carries.
+ *
+ * @packageDocumentation
+ */
+export { notifyForwarder as notify, presenceForwarder as presence, socialForwarder as social } from './realtime/social-forwarder';
+export { linkRealtimeToHub } from './realtime/hub-link';
+export type { RealtimeHubLink } from './realtime/hub-link';
+export { findRealtimeApi, isRealtimeApi } from './realtime/page-runtime';
+export {
+  REALTIME_FAILED_EVENT,
+  REALTIME_FEATURE_VERSION,
+  REALTIME_READY_EVENT,
+  REALTIME_SINGLETON_API,
+  SESSION_EVENT,
+} from './realtime/runtime-api';
+export type * from './realtime/types';