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

package/src/api/reports.ts

@@ -1,208 +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'] },
-    },
-  }),
-};
+/**
+ * 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

@@ -1,47 +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>;
+/**
+ * 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>;