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

package/src/api/reports.ts

@@ -0,0 +1,208 @@
+/**
+ * Reports and suggestions: players flagging problems (multiplayer-impl.md
+ * §5.3) and proposing game ideas (§5.5).
+ *
+ * A report only says *what* is reported; the hub builds the evidence
+ * snapshot from its own records. Suggestions are filtered, reviewed by an
+ * admin, and only approved ones reach the public board.
+ */
+import { z } from 'zod';
+import { Millis, Ok } from '../common';
+import { LooseNumber } from '../coerce';
+import { ContentRejected, ErrorBody } from '../errors';
+import { requireActive, requireClaimed, session } from '../middleware';
+import { Presence } from './social/presence';
+
+/** What is being reported. */
+export const ReportKind = z.enum(['message', 'user', 'username', 'suggestion', 'room_chat', 'presence'], {
+  error: 'kind must be one of message, user, username, suggestion, room_chat, presence.',
+});
+
+/** A report kind. */
+export type ReportKind = z.infer<typeof ReportKind>;
+
+/** Why, from a fixed list (there is no free text). */
+export const ReportReason = z.enum(['mean', 'bad_words', 'personal', 'inappropriate', 'spam', 'other'], {
+  error: 'reason must be one of mean, bad_words, personal, inappropriate, spam, other.',
+});
+
+/** A report reason. */
+export type ReportReason = z.infer<typeof ReportReason>;
+
+/**
+ * `POST /social/reports`. Loose on purpose: anything else the client sends
+ * (an evidence snapshot, quoted text) is ignored, because the hub builds the
+ * snapshot from its own records.
+ */
+export const ReportInput = z.looseObject({
+  kind: ReportKind,
+  /**
+   * The reported player. `0` for a suggestion: the hub finds its author from
+   * `refId`. Read like `Number(x)`: anything that is not a player's id is a 404.
+   */
+  targetUserId: LooseNumber.catch(Number.NaN),
+  /**
+   * What exactly: the message id (`message`), the suggestion id
+   * (`suggestion`) or the room code (`room_chat`). Kept to 64 characters.
+   */
+  refId: z.union([z.string(), z.number()]).nullable().optional(),
+  reason: ReportReason,
+});
+
+/** A report. */
+export type ReportInput = z.infer<typeof ReportInput>;
+
+/** A direct message as a report snapshot keeps it. */
+export const ReportedMessage = z.object({
+  id: z.number().int().positive(),
+  /** The sender's user id. */
+  from: z.number().int(),
+  /** The recipient's user id. */
+  to: z.number().int(),
+  /** When it was sent (epoch ms). */
+  at: Millis,
+  /** The text, or the quick-chat phrase's text (`''` for an unknown phrase). */
+  text: z.string(),
+  /** The quick-chat phrase id, when it was one. */
+  quick: z.string().optional(),
+});
+
+/** A reported direct message. */
+export type ReportedMessage = z.infer<typeof ReportedMessage>;
+
+/**
+ * The evidence the hub records with a report, from its own records (stored
+ * as `snapshot_json`; the admin console shows it). Always the reported
+ * player; then per kind: `message` adds the message and up to 5 before it in
+ * the conversation (oldest first), `suggestion` its title, body and status,
+ * `presence` their status line (`null` when offline), `room_chat` the room
+ * code (room chat isn't stored).
+ */
+export const ReportSnapshot = z.object({
+  userId: z.number().int(),
+  username: z.string(),
+  message: ReportedMessage.optional(),
+  context: z.array(ReportedMessage).optional(),
+  title: z.string().optional(),
+  body: z.string().optional(),
+  status: z.string().optional(),
+  detail: z.string().optional(),
+  presence: Presence.nullable().optional(),
+  room: z.string().optional(),
+});
+
+/** A report's evidence snapshot. */
+export type ReportSnapshot = z.infer<typeof ReportSnapshot>;
+
+/** A suggestion's review status. Only `approved`, `planned` and `done` are on the public board. */
+export const SuggestionStatus = z.enum(['pending', 'approved', 'planned', 'done', 'removed', 'withdrawn']);
+
+/** A suggestion status. */
+export type SuggestionStatus = z.infer<typeof SuggestionStatus>;
+
+/** A suggestion id. */
+export const SuggestionId = z.number().int().positive();
+
+/** A game suggestion. */
+export const Suggestion = z.object({
+  id: SuggestionId,
+  title: z.string(),
+  /** The description. */
+  body: z.string(),
+  status: SuggestionStatus,
+  /** Upvotes. */
+  votes: z.number().int().nonnegative(),
+  /** You upvoted it. */
+  voted: z.boolean(),
+  /** You suggested it. */
+  mine: z.boolean(),
+  /** The reviewer's note to the author, `''` when none. */
+  adminNote: z.string(),
+  /** When it was suggested (epoch ms). */
+  createdAt: Millis,
+  /** The author's username: only once it is on the public board (and always in admin views). */
+  author: z.string().optional(),
+});
+
+/** A game suggestion. */
+export type Suggestion = z.infer<typeof Suggestion>;
+
+/** A vote's result: the new count and whether you are voting. */
+export const VoteResult = z.object({ votes: z.number().int().nonnegative(), voted: z.boolean() });
+
+/**
+ * `:id`, a suggestion: one on the public board to vote, your own pending one
+ * to withdraw. Read like `Number(x)`: anything that isn't one is a 404.
+ */
+const SuggestionParams = z.object({ id: LooseNumber.catch(Number.NaN) });
+
+/** The old hub's one message for a missing or non-text title or description. */
+const SuggestionText = z.string({ error: 'A suggestion needs a title and a description.' });
+
+/** The report and suggestion endpoints. */
+export const reportsEndpoints = {
+  ...requireActive.group({
+    fileReport: {
+      method: 'POST', path: '/social/reports', body: ReportInput,
+      response: z.object({
+        ok: z.literal(true),
+        /** The report's id (the open one, when you already reported the same thing). */
+        id: z.number().int().positive(),
+      }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Report a player, a message, a suggestion or a status line',
+        description: '404 when `refId` is nothing you could have seen from that player.',
+        tags: ['reports'],
+      },
+    },
+  }),
+  ...session.group({
+    listPublicSuggestions: {
+      method: 'GET', path: '/suggestions',
+      query: z.object({
+        /** `votes` (default) or `new`. */
+        sort: z.enum(['votes', 'new']).optional().catch(undefined),
+      }),
+      response: z.object({
+        /** The public board (approved, planned, done), at most 200. Ideas from suspended authors drop off. */
+        approved: z.array(Suggestion),
+        /** Your own ideas except withdrawn ones, newest first; empty unless signed in to a claimed account. */
+        mine: z.array(Suggestion),
+      }),
+      errors: { 403: ErrorBody },
+      doc: { summary: 'The ideas board, plus your own ideas', tags: ['suggestions'] },
+    },
+  }),
+  ...requireClaimed.group({
+    submitSuggestion: {
+      method: 'POST', path: '/suggestions',
+      body: z.object({ title: SuggestionText, body: SuggestionText }),
+      response: z.object({ suggestion: Suggestion }),
+      errors: {
+        400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 409: ErrorBody,
+        422: ContentRejected, 429: ErrorBody,
+      },
+      doc: {
+        summary: 'Suggest a game idea (filtered; a few a day, a capped number pending)',
+        description: '409 `too_many_pending`; 429 `rate_limited` with `retryAfterMs` past the daily limit.',
+        tags: ['suggestions'],
+      },
+    },
+    voteForSuggestion: {
+      method: 'POST', path: '/suggestions/:id/vote', params: SuggestionParams, response: VoteResult,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Upvote an idea (idempotent)', tags: ['suggestions'] },
+    },
+    removeSuggestionVote: {
+      method: 'DELETE', path: '/suggestions/:id/vote', params: SuggestionParams, response: VoteResult,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Take an upvote back (idempotent)', tags: ['suggestions'] },
+    },
+    withdrawSuggestion: {
+      method: 'DELETE', path: '/suggestions/:id', params: SuggestionParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Withdraw your own idea while it is still pending', tags: ['suggestions'] },
+    },
+  }),
+};

package/src/api/social/config.ts

@@ -0,0 +1,47 @@
+/**
+ * The site-wide social configuration every social UI renders from
+ * (`GET /social/config`, `ev:config`, the `hello` snapshot).
+ */
+import { z } from 'zod';
+import { ChatMode } from '../../entities';
+
+
+/** A quick-chat phrase id: a hub phrase (`gg`), an emote (`e:<emoji>`) or a game phrase (`g:<slug>:<n>`). */
+export const QuickId = z.string().min(1);
+
+/** A non-negative character limit. */
+const CharLimit = z.number().int().nonnegative();
+
+/** Text length limits, in characters. */
+export const SocialLimits = z.object({
+  dmMaxChars: CharLimit,
+  roomChatMaxChars: CharLimit,
+  suggestionTitleMax: CharLimit,
+  suggestionBodyMax: CharLimit,
+});
+
+/** The site-wide social configuration. */
+export const SocialConfig = z.object({
+  /** The site-wide chat mode (operator setting tightened by the admin switch). */
+  chatMode: ChatMode,
+  /** The AI safety reviewer is configured. */
+  ai: z.boolean(),
+  /** Where parents can reach the operator, `''` when unset. */
+  contactUrl: z.string(),
+  /** The public "how chat is kept safe" page. */
+  parentsUrl: z.string(),
+  /** The Web Push VAPID public key (base64url), `''` when push isn't configured. */
+  vapidPublicKey: z.string(),
+  /** Every quick-chat phrase, id to text: hub phrases, emotes and every game's phrases. */
+  quickChat: z.record(QuickId, z.string()),
+  /** The emote emoji (also in `quickChat` as `e:<emoji>` ids). */
+  emotes: z.array(z.string()),
+  limits: SocialLimits,
+  /** The preset avatar ids (`a0` to `a23`). */
+  avatars: z.array(z.string()),
+  /** Present (`true`) only when the host runs in test mode (`HUB_TEST=1`). */
+  test: z.literal(true).optional(),
+});
+
+/** The social configuration. */
+export type SocialConfig = z.infer<typeof SocialConfig>;

package/src/api/social/endpoints.ts

@@ -0,0 +1,179 @@
+/**
+ * Social core REST (multiplayer-impl.md §5.1): config, your own social
+ * settings, friends and requests, blocks, player cards, recent players and
+ * online counts. Every route here is closed to suspended accounts (403
+ * `suspended`) except `GET /social/config` and `GET /social/me`, which a
+ * suspended player's UI needs to explain what happened.
+ */
+import { z } from 'zod';
+import { Ok } from '../../common';
+import { requiredId } from '../../coerce';
+import { ContentRejected, ErrorBody } from '../../errors';
+import { requireActive, requireClaimed, requireUser, session } from '../../middleware';
+import { NotifyPrefs } from '../notify';
+import { SocialConfig } from './config';
+import { Audience, FriendsList, PlayerCard, RecentPlayer, SocialMe } from './people';
+import { Counts } from './presence';
+
+/** `{ me }`: your social settings after a change. */
+export const SocialMeResult = z.object({ me: SocialMe });
+
+/** `:id`, another player's user id. A malformed id is a 400. */
+const OtherUser = z.object({ id: requiredId('id must be a user id.') });
+
+/** An {@link Audience} field, with the old hub's message for anything else. */
+const audienceField = (field: string) => z.enum(Audience.options, { error: `${field} must be friends or nobody.` });
+
+/**
+ * `POST /social/friends`: who to befriend, by id or by name, and an optional
+ * first message. `userId` wins when both are given; with neither, the player
+ * is not found (404 `no_player`).
+ */
+export const FriendRequestInput = z.object({
+  userId: requiredId('userId must be a user id.').nullish(),
+  /** A username, case-insensitive. */
+  username: z.string().optional(),
+  message: z.string().optional(),
+});
+
+/** A friend request. */
+export type FriendRequestInput = z.infer<typeof FriendRequestInput>;
+
+/** The result of `POST /social/friends`. */
+export const FriendRequestStatus = z.enum(['requested', 'friends']);
+
+/** The social core endpoints. */
+export const socialEndpoints = {
+  ...session.group({
+    getSocialConfig: {
+      method: 'GET', path: '/social/config', response: SocialConfig,
+      doc: { summary: 'The site-wide social configuration', tags: ['social'] },
+    },
+    getOnlineCounts: {
+      method: 'GET', path: '/social/counts', response: Counts,
+      errors: { 403: ErrorBody },
+      doc: { summary: 'Anonymous online counts, overall and per game', tags: ['social'] },
+    },
+  }),
+  ...requireUser.group({
+    getMySocialProfile: {
+      method: 'GET', path: '/social/me',
+      response: z.object({
+        me: SocialMe,
+        notify: NotifyPrefs,
+        /** How many browsers have a push subscription for this account. */
+        pushSubs: z.number().int().nonnegative(),
+      }),
+      errors: { 401: ErrorBody },
+      doc: { summary: 'Your social settings, notification preferences and push subscription count', tags: ['social'] },
+    },
+  }),
+  ...requireActive.group({
+    listFriendsAndRequests: {
+      method: 'GET', path: '/social/friends', response: FriendsList,
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Friends (online first), requests both ways and blocks', tags: ['social'] },
+    },
+    findPlayerByName: {
+      method: 'GET', path: '/social/players/by-name/:name',
+      params: z.object({ name: z.string() }), response: PlayerCard,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'A player card, by username', tags: ['social'] },
+    },
+    getPlayerCard: {
+      method: 'GET', path: '/social/players/:id', params: OtherUser, response: PlayerCard,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'A player card, by id (404 `no_player` when blocked by them or suspended)', tags: ['social'] },
+    },
+  }),
+  ...requireClaimed.group({
+    updateMySocialProfile: {
+      method: 'PUT', path: '/social/me',
+      body: z.object({
+        /** One of the config's preset avatar ids (else 400 `bad_avatar`). */
+        avatar: z.string().optional(),
+        privacy: audienceField('privacy').optional(),
+        dmPolicy: audienceField('dmPolicy').optional(),
+      }),
+      response: SocialMeResult,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Change your avatar, presence privacy or who may message you', tags: ['social'] },
+    },
+    setParentChatLock: {
+      method: 'POST', path: '/social/chat-lock',
+      body: z.union([
+        z.object({ on: z.literal(true) }),
+        z.object({
+          on: z.literal(false),
+          /** The account password; required to turn the lock off. */
+          password: z.string().optional(),
+        }),
+      ], { error: 'on must be true or false.' }),
+      response: SocialMeResult,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Parent chat lock: on with one tap, off only with the account password',
+        description: 'A wrong password is 403 `bad_password` (logged and rate-limited).',
+        tags: ['social'],
+      },
+    },
+    sendFriendRequest: {
+      method: 'POST', path: '/social/friends', body: FriendRequestInput,
+      response: z.object({ status: FriendRequestStatus }),
+      errors: {
+        400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody,
+        422: ContentRejected, 429: ErrorBody,
+      },
+      doc: {
+        summary: 'Send a friend request (a reverse request accepts at once)',
+        description: 'Answers `requested` without doing anything when the target blocked you or is suspended. '
+          + '`message` is moderated now and delivered as the first DM once you are friends.',
+        tags: ['social'],
+      },
+    },
+    acceptFriendRequest: {
+      method: 'POST', path: '/social/friends/:id/accept', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Accept the request from `:id`', tags: ['social'] },
+    },
+    declineFriendRequest: {
+      method: 'POST', path: '/social/friends/:id/decline', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Quietly drop the request from `:id`', tags: ['social'] },
+    },
+    removeFriend: {
+      method: 'DELETE', path: '/social/friends/:id', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Unfriend `:id`, or cancel your request to them', tags: ['social'] },
+    },
+    setFriendNotifications: {
+      method: 'PUT', path: '/social/friends/:id/notify', params: OtherUser,
+      body: z.object({ online: z.boolean({ error: 'online must be true or false.' }) }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Turn a friend's \"tell me when they're online\" bell on or off", tags: ['social'] },
+    },
+    blockPlayer: {
+      method: 'POST', path: '/social/blocks', body: z.object({ userId: requiredId('userId must be a user id.') }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: {
+        summary: 'Block a player',
+        description: 'Also unfriends, drops requests both ways and splits a shared party.',
+        tags: ['social'],
+      },
+    },
+    unblockPlayer: {
+      method: 'DELETE', path: '/social/blocks/:id', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Unblock a player', tags: ['social'] },
+    },
+    listRecentPlayers: {
+      method: 'GET', path: '/social/recent',
+      response: z.object({
+        /** Newest first, at most 50. */
+        players: z.array(RecentPlayer),
+      }),
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'People you recently played with', tags: ['social'] },
+    },
+  }),
+};

package/src/api/social/people.ts

@@ -0,0 +1,118 @@
+/**
+ * People shapes: your own social settings, friends, requests, player cards
+ * and recent players. Several are also part of the socket `hello` snapshot.
+ *
+ * Privacy rules behind them: a block in either direction looks to the
+ * blocked side like an ordinary unfriend (or a missing player), suspended
+ * players are invisible, and guests have no friends.
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+import { PlayerLite, SessionUser } from '../../entities';
+import { Presence } from './presence';
+
+/** Who may see my presence, or message me: friends, or nobody. */
+export const Audience = z.enum(['friends', 'nobody']);
+
+/** An audience setting. */
+export type Audience = z.infer<typeof Audience>;
+
+/**
+ * Your own account's social fields (`GET`/`PUT /social/me`, the `hello`
+ * snapshot's `me`). Never shown to other players.
+ */
+export const SocialMe = SessionUser.extend({
+  /** Avatar token; never empty (a default is derived from the id). */
+  avatar: PlayerLite.shape.avatar,
+  /** Who sees my presence and last-seen time. */
+  privacy: Audience,
+  /** Who may message me (and invite me). */
+  dmPolicy: Audience,
+});
+
+/** Your own social settings. */
+export type SocialMe = z.infer<typeof SocialMe>;
+
+/** A friend, with what you may see of their presence. Online friends sort first. */
+export const FriendEntry = PlayerLite.extend({
+  /** `null` when offline or hiding their presence. */
+  presence: Presence.nullable(),
+  /** "Tell me when they come online" is on for this friend. */
+  notifyOnline: z.boolean(),
+  /** When you became friends (epoch ms). */
+  since: Millis,
+  /** When they were last online (epoch ms); `0` when unknown or they hide their presence. */
+  lastSeenAt: Millis,
+});
+
+/** A friend. */
+export type FriendEntry = z.infer<typeof FriendEntry>;
+
+/** Pending friend requests both ways, newest first (blocked and suspended players left out). */
+export const FriendRequests = z.object({
+  /** Requests waiting for you. */
+  incoming: z.array(PlayerLite),
+  /** Requests you sent. */
+  outgoing: z.array(PlayerLite),
+});
+
+/** Pending friend requests. */
+export type FriendRequests = z.infer<typeof FriendRequests>;
+
+/** `GET /social/friends`: friends, requests and the players you blocked. Guests get empty lists. */
+export const FriendsList = FriendRequests.extend({
+  friends: z.array(FriendEntry),
+  /** Players you blocked, newest first. */
+  blocked: z.array(PlayerLite),
+});
+
+/** Friends, requests and blocks. */
+export type FriendsList = z.infer<typeof FriendsList>;
+
+/**
+ * What changed in `ev:friends` (the client refetches `GET /social/friends`).
+ * `restored`: a friend's suspension ended. A player you blocked only ever
+ * sees `removed`.
+ */
+export const FriendChange = z.enum(['request', 'accepted', 'removed', 'declined', 'cancelled', 'blocked', 'restored']);
+
+/** A friends-list change. */
+export type FriendChange = z.infer<typeof FriendChange>;
+
+/** My relation to another player, as their card shows it. */
+export const Relation = z.enum(['self', 'friend', 'incoming', 'outgoing', 'blocked', 'none']);
+
+/** A relation. */
+export type Relation = z.infer<typeof Relation>;
+
+/**
+ * A player card (`GET /social/players/:id`). Someone who blocked you, or who
+ * is suspended, answers 404 exactly like a player who doesn't exist.
+ */
+export const PlayerCard = PlayerLite.extend({
+  relation: Relation,
+  /** Friends only; `null` otherwise, or when offline or hidden. */
+  presence: Presence.nullable(),
+  /** A friend request can be sent (both claimed, no relation yet or theirs is pending, requests on). */
+  canFriend: z.boolean(),
+  /** Friends who take messages, while DMs are on. */
+  canMessage: z.boolean(),
+  /** Friends who take messages. */
+  canInvite: z.boolean(),
+  /** Anyone but yourself. */
+  canReport: z.boolean(),
+});
+
+/** A player card. */
+export type PlayerCard = z.infer<typeof PlayerCard>;
+
+/** Someone you recently played with (`GET /social/recent`). */
+export const RecentPlayer = PlayerLite.extend({
+  /** The game you played together. */
+  game: Slug,
+  /** When you last played together (epoch ms). */
+  lastAt: Millis,
+});
+
+/** A recent player. */
+export type RecentPlayer = z.infer<typeof RecentPlayer>;

package/src/api/social/presence.ts

@@ -0,0 +1,95 @@
+/**
+ * Presence: what a player is doing right now, as their friends see it, and
+ * the anonymous online counts (multiplayer-impl.md §4.4). Games report a
+ * {@link PresenceInput} per tab (socket op `presence`); the hub folds a
+ * user's tabs into one {@link Presence} and pushes it to friends
+ * (`ev:presence`).
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+
+/** Activity kinds, least engaged first. The most engaged tab wins; hidden or idle tabs count as `away`. */
+export const PresenceKind = z.enum(['away', 'menu', 'lobby', 'watching', 'playing']);
+
+/** An activity kind. */
+export type PresenceKind = z.infer<typeof PresenceKind>;
+
+/** A room reference friends can join with: 1 to 64 of `A-Z a-z 0-9 _ : -`. */
+export const PresenceRoom = z.string().regex(/^[A-Za-z0-9_:-]{1,64}$/);
+
+/** A game mode key: 1 to 32 of `A-Z a-z 0-9 _ -`. */
+export const PresenceMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
+
+/** The fields a tab reports and friends see back, with the limits the hub enforces. */
+const PresenceFields = z.object({
+  kind: PresenceKind,
+  /** A short status line (at most 40 characters), filtered; a rejected one is dropped. */
+  detail: z.string().max(40).optional(),
+  /** Friends may join. Only ever `true` when present. */
+  joinable: z.boolean().optional(),
+  /** Friends may watch. Only ever `true` when present. */
+  watchable: z.boolean().optional(),
+  /** Join info for friends: the game's own room reference, or the hub room's code. */
+  room: PresenceRoom.optional(),
+  /** A public lobby: friends who follow the game may get a `lobby_open` alert. */
+  public: z.boolean().optional(),
+  /** Free seats, 0 to 64. */
+  openSeats: z.number().int().min(0).max(64).optional(),
+  mode: PresenceMode.optional(),
+});
+
+/**
+ * What a game reports for its tab (socket op `presence`). The hub is
+ * lenient: an unknown `kind`, or input that isn't an object at all (`null`),
+ * counts as `{kind:'menu'}`; unknown fields, and fields that break a rule (a
+ * bad `room`, a fractional `openSeats`, a field of the wrong type), are
+ * ignored one by one, so friends only ever
+ * see {@link Presence}'s fields; `detail` is trimmed to 40 characters before
+ * filtering.
+ */
+export const PresenceInput = z.looseObject({
+  kind: PresenceKind.catch('menu'),
+  detail: z.string().optional().catch(undefined),
+  joinable: z.boolean().optional().catch(undefined),
+  watchable: z.boolean().optional().catch(undefined),
+  room: z.string().optional().catch(undefined),
+  public: z.boolean().optional().catch(undefined),
+  openSeats: z.number().optional().catch(undefined),
+  mode: z.string().optional().catch(undefined),
+}).catch({ kind: 'menu' });
+
+/** A presence report. */
+export type PresenceInput = z.input<typeof PresenceInput>;
+
+/** A user's aggregated presence: their most engaged tab, decorated by the hub. */
+export const Presence = PresenceFields.extend({
+  /** The game the tab is on, `null` on the catalog and other hub pages. */
+  game: Slug.nullable(),
+  /** That game's title, `null` with `game`. */
+  gameTitle: z.string().nullable(),
+  /** When this activity (kind + game) started (epoch ms). */
+  since: Millis,
+  /** Party size, present when the user is in a party of two or more. */
+  partySize: z.number().int().min(2).optional(),
+});
+
+/** A user's aggregated presence. */
+export type Presence = z.infer<typeof Presence>;
+
+/** A non-negative head count. */
+const HeadCount = z.number().int().nonnegative();
+
+/**
+ * Anonymous online counts (`GET /social/counts`, `ev:counts`, the `hello`
+ * snapshot): everyone with a live presence, guests and hidden players
+ * included.
+ */
+export const Counts = z.object({
+  /** Everyone online. */
+  online: HeadCount,
+  /** Players per game slug (games with nobody are absent). */
+  byGame: z.record(Slug, HeadCount),
+});
+
+/** Online counts. */
+export type Counts = z.infer<typeof Counts>;

package/src/api/social.ts

@@ -0,0 +1,9 @@
+/**
+ * Friends, blocks, the social profile and settings, player cards and counts,
+ * plus the shared social shapes (config, presence, people) the socket
+ * `hello` snapshot and events reuse. Split by topic under `social/`.
+ */
+export * from './social/config';
+export * from './social/presence';
+export * from './social/people';
+export * from './social/endpoints';