@diffenderfer-games/hub-contract 0.0.0-stage → 2.0.0-next.0

package/src/api/mp/chat.ts

@@ -0,0 +1,36 @@
+/**
+ * Group chat in hub rooms and parties (multiplayer.md §4.3, §4.8): what a
+ * player sends, and the moderated line everyone receives.
+ */
+import { z } from 'zod';
+import { UserId } from '../../common';
+
+
+/**
+ * A chat send: a quick-chat phrase id, or free text. When `quick` is set it
+ * wins and `text` is ignored.
+ */
+export const ChatSend = z.object({
+  /** Free text; only allowed in mode `on`, then moderated. */
+  text: z.string().optional(),
+  /** A quick-chat phrase id (hub phrase, `e:<emoji>` emote or game phrase). */
+  quick: z.string().optional(),
+});
+
+/** The line as delivered: the (possibly softened) text, and the phrase id for quick-chat. */
+export const ChatLine = z.object({
+  text: z.string(),
+  /** Set when the line is a quick-chat phrase. */
+  quick: z.string().optional(),
+  /** Moderation reworded the text. */
+  softened: z.literal(true).optional(),
+});
+
+/** A delivered chat line. */
+export type ChatLine = z.infer<typeof ChatLine>;
+
+/** A chat line pushed to a room or party, with its sender. */
+export const ChatLineEvent = ChatLine.extend({ from: UserId });
+
+/** The error codes a chat send can fail with (besides its surface's own). */
+export const CHAT_ERRORS = ['rate_limited', 'content_rejected', 'bad_quick'] as const;

package/src/api/mp/parties.ts

@@ -0,0 +1,108 @@
+/**
+ * Invites, parties and launches (multiplayer-impl.md §5.6): the shapes the
+ * mp endpoints, the `invite` / `invite.update` / `party` socket events and
+ * the `hello` snapshot share. All of it lives in the hub's memory; a restart
+ * drops it.
+ */
+import { z } from 'zod';
+import { Millis, Slug, UserId } from '../../common';
+import { PlayerLite } from '../../entities';
+
+/** A game mode key, as the game's `multiplayer.modes[].key` declares it: `[A-Za-z0-9_-]{1,32}`. */
+export const GameMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
+
+/** An opaque hub-minted id (party, invite, room): base64url text. */
+export const OpaqueId = z.string().min(1);
+
+/** A `joinInfo` key: `[A-Za-z0-9_]{1,32}`. */
+const JoinInfoKey = z.string().regex(/^[A-Za-z0-9_]{1,32}$/);
+
+/**
+ * Where a party should connect, as its leader publishes it (e.g.
+ * `{ room: 'ABCDE' }`): at most 8 short keys, string values of at most 64
+ * characters. The hub accepts finite numbers and stores them as strings.
+ */
+export const JoinInfo = z
+  .record(JoinInfoKey, z.union([z.string().max(64), z.number().transform(String)]))
+  .refine((joinInfo) => Object.keys(joinInfo).length <= 8, 'info may have at most 8 keys');
+
+/** A party's join info. */
+export type JoinInfo = z.infer<typeof JoinInfo>;
+
+/** A group of 2 to 8 players moving between games together. A user is in at most one. */
+export const Party = z.object({
+  id: OpaqueId,
+  game: Slug,
+  /** Present when the party formed for a specific mode (`race` for race invites). */
+  mode: GameMode.optional(),
+  leaderId: UserId,
+  members: z.array(PlayerLite),
+  /** `null` until the leader publishes where to connect. */
+  joinInfo: JoinInfo.nullable(),
+  /** Epoch ms. */
+  createdAt: Millis,
+});
+
+/** A party. */
+export type Party = z.infer<typeof Party>;
+
+/** "Come play <game> with me": pending until accepted, declined, cancelled or expired. */
+export const Invite = z.object({
+  id: OpaqueId,
+  from: PlayerLite,
+  to: PlayerLite,
+  game: Slug,
+  gameTitle: z.string(),
+  mode: GameMode.optional(),
+  /** The inviter's party the invitee joins on accept. */
+  partyId: OpaqueId,
+  /** Epoch ms. */
+  expiresAt: Millis,
+});
+
+/** An invite. */
+export type Invite = z.infer<typeof Invite>;
+
+/** How an invite ended. */
+export const InviteStatus = z.enum(['accepted', 'declined', 'expired', 'cancelled']);
+
+/** How an invite ended. */
+export type InviteStatus = z.infer<typeof InviteStatus>;
+
+/** A single-use launch token plus the game URL that redeems it (`?hub_launch=<token>`). */
+export const LaunchTicket = z.object({
+  launchToken: z.string(),
+  /** `/<slug>/<lobby>` with `hub_launch` appended. */
+  url: z.string(),
+});
+
+/** A launch ticket. */
+export type LaunchTicket = z.infer<typeof LaunchTicket>;
+
+/** Why the hub is bringing a player into a game. */
+export const LaunchKind = z.enum(['host', 'guest', 'join', 'watch']);
+
+/**
+ * What a game's `hub.mp.onLaunch` receives after redeeming a launch token.
+ * Party fields reflect the party as it is at redemption time.
+ */
+export const Launch = z.object({
+  kind: LaunchKind,
+  game: Slug,
+  mode: GameMode.optional(),
+  /** Host and guest launches: the party they belong to. */
+  partyId: OpaqueId.optional(),
+  /** The party now; `null` when it has dissolved since the token was minted. */
+  party: Party.nullable().optional(),
+  /** The party's join info now; `null` when unset or the party is gone. */
+  joinInfo: JoinInfo.nullable().optional(),
+  /** Join and watch launches: the room code the friend's presence advertised. */
+  room: z.string().optional(),
+  /** Guest launches: the party leader (`null` if the account is gone). */
+  host: PlayerLite.nullable().optional(),
+  /** Join and watch launches: the friend being joined (`null` if the account is gone). */
+  target: PlayerLite.nullable().optional(),
+});
+
+/** A launch. */
+export type Launch = z.infer<typeof Launch>;

package/src/api/mp/races.ts

@@ -0,0 +1,211 @@
+/**
+ * Race shapes (docs/plans/race.md): params, live stats, racers and decided
+ * results. Shared by the `race.*` socket ops and events, the race block of
+ * a room, and `GET /race/history`. Each rule here is defined once.
+ */
+import { z } from 'zod';
+import { HexColor, Millis, Slug, UserId } from '../../common';
+import { RACE_STATS_LIMITS } from '../../limits';
+
+/** A race param or stat key: a letter, then up to 23 letters, digits or `_`. */
+export const RaceKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,23}$/);
+
+/** A race param value, one of the game's declared options: a number, a boolean or a short token. */
+export const RaceParamValue = z.union([
+  z.number(),
+  z.boolean(),
+  z.string().regex(/^[A-Za-z0-9_-]{1,24}$/),
+]);
+
+/**
+ * The creator's choices, keyed by the manifest's `race.params[].key`. The
+ * hub keeps only declared keys and option values (anything else becomes the
+ * param's default), so everyone gets the same puzzle.
+ */
+export const RaceParams = z.record(RaceKey, RaceParamValue);
+
+/** A race's params. */
+export type RaceParams = z.infer<typeof RaceParams>;
+
+/** Live stat values are clamped to ±1e9. */
+const STAT_LIMIT = 1e9;
+
+/**
+ * A live stat value: a finite number (clamped to ±1e9), a boolean or a
+ * `#rrggbb` colour (lower-cased). Never text.
+ */
+export const RaceStatValue = z.union([
+  z.number().transform((n) => Math.max(-STAT_LIMIT, Math.min(STAT_LIMIT, n))),
+  z.boolean(),
+  HexColor.transform((c) => c.toLowerCase()),
+]);
+
+/** A live stat value, as cleaned by the hub. */
+export type RaceStatValue = z.output<typeof RaceStatValue>;
+
+/**
+ * A racer's live stats, keyed like the manifest's `race.stats[].key`: at
+ * most 12 keys and 600 bytes of JSON once cleaned.
+ */
+export const RaceStats = z
+  .record(RaceKey, RaceStatValue)
+  .refine((s) => Object.keys(s).length <= RACE_STATS_LIMITS.maxKeys, `at most ${String(RACE_STATS_LIMITS.maxKeys)} stats`)
+  .refine((s) => JSON.stringify(s).length <= RACE_STATS_LIMITS.maxBytes, 'stats too large');
+
+/** A racer's stats. */
+export type RaceStats = z.infer<typeof RaceStats>;
+
+/** How far along a racer is, 0 to 1. The hub clamps values outside that range. */
+export const RaceProgress = z.number().transform((n) => Math.max(0, Math.min(1, n)));
+
+/** A race room's phase: waiting for racers → countdown → racing → done (→ countdown on a rematch). */
+export const RacePhase = z.enum(['waiting', 'countdown', 'racing', 'done']);
+
+/** A racer's state while the race runs. */
+export const RacerState = z.enum(['racing', 'finished', 'lost', 'forfeit', 'disconnected']);
+
+/** A value of {@link RacerState}. */
+export type RacerState = z.infer<typeof RacerState>;
+
+/** How a race ended: the winner finished, everyone else lost / gave up / dropped, or time ran out. */
+export const RaceOutcome = z.enum(['finished', 'lost', 'forfeit', 'disconnected', 'timeout']);
+
+/** A value of {@link RaceOutcome}. */
+export type RaceOutcome = z.infer<typeof RaceOutcome>;
+
+/** One racer's result. `beaten`: still racing when someone else won. */
+export const RacerResult = z.enum(['won', 'beaten', 'lost', 'forfeit', 'disconnected', 'timeout']);
+
+/** A value of {@link RacerResult}. */
+export type RacerResult = z.infer<typeof RacerResult>;
+
+/** Fields every live racer line has (room roster and result card). */
+const RacerLine = z.object({
+  userId: UserId,
+  /** The racer's username when the race began. */
+  name: z.string(),
+  /** Avatar token; never empty. */
+  avatar: z.string(),
+  stats: RaceStats,
+  /** 0..1, when the game reports it. */
+  progress: RaceProgress.optional(),
+});
+
+/** A racer in a race room's roster (RoomInfo.race.players). */
+export const Racer = RacerLine.extend({
+  state: RacerState,
+  /** Server-measured ms from the go to finishing or dropping out. */
+  ms: z.number().int().nonnegative().optional(),
+});
+
+/** A racer in a race room. */
+export type Racer = z.infer<typeof Racer>;
+
+/** One racer's line in a {@link RaceResult}. */
+export const RaceResultPlayer = RacerLine.extend({
+  /** 1 for the winner. */
+  place: z.number().int().positive(),
+  result: RacerResult,
+  /** Server-measured ms from the go to finishing or dropping out (the race's end for those still in). */
+  ms: z.number().int().nonnegative(),
+});
+
+/** Fields a decided race has both live and in the history. */
+const DecidedRace = z.object({
+  game: Slug,
+  params: RaceParams,
+  outcome: RaceOutcome,
+  /** Epoch ms of the go. */
+  startedAt: Millis,
+  /** Epoch ms. */
+  endedAt: Millis,
+  /** ms from the go to the decision. */
+  durationMs: z.number().int().nonnegative(),
+});
+
+/** A decided race: the `race.result` event, the `race.finish` ack and RoomInfo.race.result. */
+export const RaceResult = DecidedRace.extend({
+  /** The race's id in the history; `null` if recording it failed. */
+  id: z.number().int().positive().nullable(),
+  /** The room code. */
+  room: z.string(),
+  /** 1 for the room's first race, +1 per rematch. */
+  round: z.number().int().positive(),
+  seed: z.number().int().positive(),
+  /** `null` when nobody won (time ran out, or everyone dropped out). */
+  winnerId: UserId.nullable(),
+  /** In finishing order (place 1 first). */
+  players: z.array(RaceResultPlayer),
+});
+
+/** A decided race. */
+export type RaceResult = z.infer<typeof RaceResult>;
+
+/** The referee's view of a race room (RoomInfo.race). */
+export const RaceState = z.object({
+  phase: RacePhase,
+  /** 1 for the first race in the room, +1 per rematch; 0 while waiting for the first. */
+  round: z.number().int().nonnegative(),
+  params: RaceParams,
+  /** The countdown can start once this many racers are seated. */
+  minPlayers: z.number().int().positive(),
+  /** Everyone racing this round (empty while waiting for the first). */
+  players: z.array(Racer),
+  /** Who asked for a rematch since the last race. */
+  rematch: z.array(UserId),
+  /** Present once the countdown starts (never before, so nobody can pre-solve). */
+  seed: z.number().int().positive().optional(),
+  /** Epoch ms of the go (server clock); present with `seed`. */
+  startAt: Millis.optional(),
+  /** Present once the round is decided. */
+  result: RaceResult.optional(),
+});
+
+/** A race room's referee state. */
+export type RaceState = z.infer<typeof RaceState>;
+
+/** The countdown began (`race.start`): build the puzzle from `seed` + `params`. */
+export const RaceStart = z.object({
+  roomId: z.string(),
+  round: z.number().int().positive(),
+  seed: z.number().int().positive(),
+  params: RaceParams,
+  /** Epoch ms of the go (server clock). */
+  startAt: Millis,
+  /** ms until the go. */
+  startsIn: z.number().int().nonnegative(),
+  /** The racers' user ids. */
+  players: z.array(UserId),
+});
+
+/** A racer in a history record. Suspended opponents are `hidden`: id 0, name "A player", no avatar. */
+export const RaceRecordPlayer = z.object({
+  /** 0 when hidden. */
+  userId: z.number().int().nonnegative(),
+  username: z.string(),
+  /** Avatar token; `''` when hidden. */
+  avatar: z.string(),
+  guest: z.boolean(),
+  place: z.number().int().positive(),
+  result: RacerResult,
+  /** Server-measured ms from the go to finishing or dropping out. */
+  ms: z.number().int().nonnegative().optional(),
+  progress: RaceProgress.optional(),
+  stats: RaceStats,
+  hidden: z.literal(true).optional(),
+});
+
+/** One past race the player was in (`GET /race/history`). */
+export const RaceRecord = DecidedRace.extend({
+  id: z.number().int().positive(),
+  gameTitle: z.string(),
+  /** `null` when nobody won; 0 when the winner is hidden (suspended). */
+  winnerId: z.number().int().nonnegative().nullable(),
+  /** The signed-in player's own line (`null` only if their row is missing). */
+  me: RaceRecordPlayer.nullable(),
+  /** In place order. */
+  players: z.array(RaceRecordPlayer),
+});
+
+/** A past race. */
+export type RaceRecord = z.infer<typeof RaceRecord>;

package/src/api/mp/rooms.ts

@@ -0,0 +1,90 @@
+/**
+ * Hub relay rooms (multiplayer-impl.md §6): realtime multiplayer for static
+ * games, relayed (never refereed) by the hub. A race is a room with a
+ * `race` block on top. Shared by the `room.*` / `race.*` ops and events and
+ * the `hello` snapshot.
+ */
+import { z } from 'zod';
+import { Json, Slug, UserId } from '../../common';
+import { ChatMode } from '../../entities';
+import { GameMode, OpaqueId } from './parties';
+import { RaceState } from './races';
+
+/** A room's join code: 5 characters from `A-Z` and `2-9` (no `I`, `O`, `0`, `1`). */
+export const RoomCode = z.string().regex(/^[A-HJ-NP-Z2-9]{5}$/);
+
+/** A room's lifecycle: new players join only in the lobby. */
+export const RoomPhase = z.enum(['lobby', 'playing', 'ended']);
+
+/**
+ * Who hears a send. `host` (default): guests' unaddressed sends reach the
+ * host only. `relay`: every unaddressed send reaches everyone, sender
+ * included.
+ */
+export const RoomModel = z.enum(['host', 'relay']);
+
+/** A seat in a room, keyed by user (any tab of that user reclaims it). */
+export const RoomSeat = z.object({
+  userId: UserId,
+  /** The player's username when they sat down. */
+  name: z.string(),
+  /** Avatar token; never empty. */
+  avatar: z.string(),
+  ready: z.boolean(),
+  /** `false` while the seat is held for a dropped player's reconnect grace. */
+  connected: z.boolean(),
+  /** Small per-seat game data (team, colour…), at most 2 KB of JSON. */
+  data: Json.optional(),
+});
+
+/** The public description of a room (`room` event, room and race acks, the `hello` snapshot). */
+export const RoomInfo = z.object({
+  id: OpaqueId,
+  code: RoomCode,
+  game: Slug,
+  /** `race` for race rooms. */
+  mode: GameMode.optional(),
+  hostId: UserId,
+  /** Listed in `room.list` / `race.list`. */
+  public: z.boolean(),
+  phase: RoomPhase,
+  maxPlayers: z.number().int().positive(),
+  model: RoomModel,
+  seats: z.array(RoomSeat),
+  /** How many are watching. */
+  spectators: z.number().int().nonnegative(),
+  /** The chat mode for the seated players. */
+  chatMode: ChatMode,
+  /** Present on race rooms. */
+  race: RaceState.optional(),
+});
+
+/** A room. */
+export type RoomInfo = z.infer<typeof RoomInfo>;
+
+/** A room's shared state for late joiners: a JSON object, at most 32 KB. */
+export const RoomState = z.record(z.string(), Json);
+
+/** A relayed game message (`room.msg`, and a join's replay history). */
+export const RoomMessage = z.object({
+  from: UserId,
+  data: Json,
+  /** Per-room sequence number, shared with state patches. */
+  seq: z.number().int().positive(),
+  /** Set when the message went to one seat only. */
+  to: UserId.optional(),
+});
+
+/** How to find a room: by its code (case-insensitive) or its id. */
+export const RoomTarget = z.object({
+  code: z.string().optional(),
+  id: z.string().optional(),
+  /** Watch instead of taking a seat (if the game allows spectators). */
+  spectate: z.boolean().optional(),
+});
+
+/** Why a room went away for this tab (`room.closed`). */
+export const RoomClosedReason = z.enum(['empty', 'ended', 'host_left', 'moved', 'other_tab', 'removed']);
+
+/** Why a seat was freed (`room.abandoned`). */
+export const SeatGoneReason = z.enum(['left', 'abandoned', 'kicked']);

package/src/api/mp/snapshot.ts

@@ -0,0 +1,17 @@
+/** The multiplayer part of the socket `hello` snapshot (multiplayer-impl.md §4.5). */
+import { z } from 'zod';
+import { Invite, Party } from './parties';
+import { RoomInfo } from './rooms';
+
+/**
+ * The multiplayer fields of the `hello` ack, to spread into the snapshot
+ * schema (`z.object({ ...other, ...MultiplayerSnapshot.shape })`).
+ */
+export const MultiplayerSnapshot = z.object({
+  /** Pending invites addressed to me. */
+  invites: z.array(Invite),
+  /** The party I'm in, or `null`. */
+  party: Party.nullable(),
+  /** The room seat I still hold (not ended), or `null`; `room.join` it again to reconnect. */
+  room: RoomInfo.nullable(),
+});

package/src/api/mp.ts

@@ -0,0 +1,110 @@
+/**
+ * Multiplayer REST (multiplayer-impl.md §5.6): invites, launch tokens,
+ * parties, joining a friend's game, and game-server tickets. Every route
+ * needs an active account; invites need a claimed one. The live state is in
+ * the hub's memory and changes are pushed over `/_ws` (`invite`,
+ * `invite.update`, `party`).
+ */
+import { z } from 'zod';
+import { Millis, Ok, Slug, UserIdParam } from '../common';
+import { ErrorBody } from '../errors';
+import { requireActive, requireClaimed } from '../middleware';
+import { GameMode, Invite, JoinInfo, Launch, LaunchTicket, OpaqueId } from './mp/parties';
+
+export * from './mp/chat';
+export * from './mp/parties';
+export * from './mp/races';
+export * from './mp/rooms';
+export * from './mp/snapshot';
+
+/** `:id` of an invite or party. */
+const IdParams = z.object({ id: OpaqueId });
+
+/** The answer to `POST /mp/invites`: the invite, plus the inviter's own `host` launch. */
+export const InviteCreated = LaunchTicket.extend({ invite: Invite });
+
+/** A game-server identity ticket. */
+export const GameTicket = z.object({
+  /** `base64url(payload).base64url(hmac)`, verified offline by the game's server with `HUB_APP_KEY`. */
+  ticket: z.string(),
+  /** Epoch ms; tickets live 60 s. */
+  expiresAt: Millis,
+});
+
+/** The mp endpoints. */
+export const mpEndpoints = {
+  ...requireClaimed.group({
+    sendGameInvite: {
+      method: 'POST', path: '/mp/invites',
+      body: z.object({
+        /** The friend to invite. */
+        to: UserIdParam,
+        game: Slug,
+        /** One of the game's modes; race-only games default to `race`. */
+        mode: GameMode.nullish(),
+      }),
+      response: InviteCreated,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Invite a friend to a game; creates or reuses your party and returns your host launch',
+        tags: ['mp'],
+      },
+    },
+    acceptGameInvite: {
+      method: 'POST', path: '/mp/invites/:id/accept', params: IdParams, response: LaunchTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: "Accept an invite: join the inviter's party and get a guest launch", tags: ['mp'] },
+    },
+    declineGameInvite: {
+      method: 'POST', path: '/mp/invites/:id/decline', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Decline an invite addressed to you', tags: ['mp'] },
+    },
+    cancelGameInvite: {
+      method: 'DELETE', path: '/mp/invites/:id', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Cancel an invite you sent', tags: ['mp'] },
+    },
+  }),
+  ...requireActive.group({
+    redeemLaunchToken: {
+      method: 'GET', path: '/mp/launch/:token', params: z.object({ token: z.string() }),
+      response: z.object({ launch: Launch }),
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Redeem a launch token (single use, bound to the signed-in user)', tags: ['mp'] },
+    },
+    setPartyJoinInfo: {
+      method: 'POST', path: '/mp/parties/:id/join-info', params: IdParams,
+      body: z.object({ info: JoinInfo }),
+      response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Party leader: publish where the party should connect', tags: ['mp'] },
+    },
+    leaveParty: {
+      method: 'POST', path: '/mp/parties/:id/leave', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Leave a party (the leader role passes on; an empty party dissolves)', tags: ['mp'] },
+    },
+    launchIntoFriendsRoom: {
+      method: 'POST', path: '/mp/join',
+      body: z.object({
+        /** The player whose game to join or watch. */
+        userId: UserIdParam,
+        /** Watch instead of play. */
+        watch: z.boolean().optional(),
+        /** Joining a stranger's public lobby from a `lobby_open` alert (not a friend's game). */
+        fromLobbyOpen: z.boolean().optional(),
+      }),
+      response: LaunchTicket,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: "A Join or Watch launch into the room a friend's presence advertises", tags: ['mp'] },
+    },
+    getGameServerTicket: {
+      method: 'POST', path: '/mp/ticket',
+      body: z.object({ slug: Slug }),
+      response: GameTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 429: ErrorBody },
+      doc: { summary: "A 60 s identity ticket for a game's own server", tags: ['mp'] },
+    },
+  }),
+};

package/src/api/notify.ts

@@ -0,0 +1,111 @@
+/**
+ * Notification preferences and Web Push subscriptions
+ * (multiplayer-impl.md §5.4). Everything is off by default and claimed-only.
+ * Which channel an alert takes (a live `ev:notice` toast or a push) is the
+ * hub's decision; see `ev:notice`.
+ */
+import { z } from 'zod';
+import { Ok, Slug, UserId } from '../common';
+import { ErrorBody } from '../errors';
+import { requireActive, requireClaimed } from '../middleware';
+
+/** Notification preferences (`GET`/`PUT /social/notify`, `GET /social/me`). */
+export const NotifyPrefs = z.object({
+  /** Push a new DM when no tab is open. */
+  dm: z.boolean(),
+  /** Push a friend request when no tab is open. */
+  friend_request: z.boolean(),
+  /** "Tell me when any friend comes online", on top of the per-friend bells. */
+  friendOnlineAll: z.boolean(),
+  /** Friends whose bell is on, ascending. */
+  friendOnline: z.array(UserId),
+  /** Games followed for "someone's waiting in a lobby", sorted. */
+  lobbyOpen: z.array(Slug),
+});
+
+/** Notification preferences. */
+export type NotifyPrefs = z.infer<typeof NotifyPrefs>;
+
+/** The preference kinds `PUT /social/notify` can flip. */
+export const NotifyPrefKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open'], {
+  error: 'kind must be dm, friend_request, friend_online or lobby_open.',
+});
+
+/** A preference kind. */
+export type NotifyPrefKind = z.infer<typeof NotifyPrefKind>;
+
+/**
+ * One `PUT /social/notify` change. `target`: for `friend_online`, a friend's
+ * id (a number, or its decimal string) for that friend's bell, or absent
+ * (`''`, `null`) for the "any friend" switch; for `lobby_open`, the game slug.
+ * Ignored for `dm` and `friend_request`. Any other number or text is a 404
+ * (not a friend, no such game), as on the old hub. `enabled` is checked
+ * first, so its message wins when both fields are wrong.
+ */
+export const NotifyChange = z.object({
+  enabled: z.boolean({ error: 'enabled must be true or false.' }),
+  kind: NotifyPrefKind,
+  target: z.union([z.string(), z.number()]).nullable().optional(),
+});
+
+/** A notification preference change. */
+export type NotifyChange = z.infer<typeof NotifyChange>;
+
+/** The 400 for a subscription the hub can't push to (malformed, or not on a known push service). */
+export const UNSUPPORTED_SUBSCRIPTION = "That browser subscription isn't supported.";
+
+/**
+ * A browser push subscription, as `PushSubscription.toJSON()` gives it. The
+ * endpoint must be `https` on a known push service; `p256dh` is a 65-byte
+ * and `auth` an at-least-16-byte base64url key.
+ */
+export const PushSubscriptionJson = z.object({
+  endpoint: z.string().max(1000, { error: UNSUPPORTED_SUBSCRIPTION }),
+  /** When the subscription expires (epoch ms), `null` when it doesn't. */
+  expirationTime: z.number().nullable().optional(),
+  keys: z.object({
+    p256dh: z.string().max(200, { error: UNSUPPORTED_SUBSCRIPTION }),
+    auth: z.string().max(100, { error: UNSUPPORTED_SUBSCRIPTION }),
+  }),
+});
+
+/** A browser push subscription. */
+export type PushSubscriptionJson = z.infer<typeof PushSubscriptionJson>;
+
+/** The notification endpoints. */
+export const notifyEndpoints = {
+  ...requireActive.group({
+    getNotificationPreferences: {
+      method: 'GET', path: '/social/notify', response: NotifyPrefs,
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Your notification preferences (all off for guests)', tags: ['notify'] },
+    },
+    unsubscribeFromPush: {
+      method: 'DELETE', path: '/social/push',
+      body: z.object({ endpoint: z.string({ error: 'endpoint is required.' }).min(1, { error: 'endpoint is required.' }) }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: "Forget one of this account's push subscriptions", tags: ['notify'] },
+    },
+  }),
+  ...requireClaimed.group({
+    setNotificationPreferences: {
+      method: 'PUT', path: '/social/notify', body: NotifyChange, response: NotifyPrefs,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: {
+        summary: 'Flip one notification preference',
+        description: '404 for a friend bell on a non-friend or an unknown game; 409 past 50 followed games.',
+        tags: ['notify'],
+      },
+    },
+    subscribeToPush: {
+      method: 'POST', path: '/social/push',
+      body: z.object({ subscription: z.union([PushSubscriptionJson, z.never()], { error: UNSUPPORTED_SUBSCRIPTION }) }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: {
+        summary: "Store this browser's push subscription",
+        description: 'One browser is one endpoint: subscribing from another account moves it. Past the per-user cap the oldest is dropped.',
+        tags: ['notify'],
+      },
+    },
+  }),
+};