@thegeem/protocol 0.1.37 → 0.1.38

package/dist/index.cjs

@@ -30,11 +30,15 @@ __export(index_exports, {
   MODES: () => MODES,
   MODE_IDS: () => MODE_IDS,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  REJECT_REASONS: () => REJECT_REASONS,
   ROOM_ALPHABET: () => ROOM_ALPHABET,
+  SUBMISSION_KINDS: () => SUBMISSION_KINDS,
+  SUBMISSION_STATUSES: () => SUBMISSION_STATUSES,
   gameIdForPv: () => gameIdForPv,
   gamesForPv: () => gamesForPv,
   modesForGame: () => modesForGame,
-  normalizeWesternDigits: () => normalizeWesternDigits
+  normalizeWesternDigits: () => normalizeWesternDigits,
+  sanitizeName: () => sanitizeName
 });
 module.exports = __toCommonJS(index_exports);
 var import_zod = require("zod");
@@ -77,7 +81,8 @@ var CHARACTER_IDS = ["m", "f"];
 var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 var UNSAFE_CHARS = /[\p{Cc}\u202A-\u202E\u2066-\u2069<>]/gu;
 var normalizeWesternDigits = (s) => s.replace(/[٠-٩۰-۹]/g, (d) => String("\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) >= 0 ? "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) : "\u06F0\u06F1\u06F2\u06F3\u06F4\u06F5\u06F6\u06F7\u06F8\u06F9".indexOf(d)));
-var DisplayName = import_zod.z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim()).refine((s) => s.length >= 1, "name is empty after sanitizing");
+var sanitizeName = (s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim();
+var DisplayName = import_zod.z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform(sanitizeName).refine((s) => s.length >= 1, "name is empty after sanitizing");
 var RoomCode = import_zod.z.string().trim().toUpperCase().regex(new RegExp(`^[${ROOM_ALPHABET}]{${LIMITS.ROOM_CODE_LEN}}$`), "bad room code");
 var PlayerId = import_zod.z.string().max(40);
 var HelpType = import_zod.z.enum([
@@ -266,6 +271,9 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   // Drawer passes on the served word (capped per draw-turn; relay serves a fresh one).
   import_zod.z.object({ t: import_zod.z.literal("skipWord") })
 ]);
+var SUBMISSION_STATUSES = ["pending", "accepted", "rejected"];
+var SUBMISSION_KINDS = ["new", "edit"];
+var REJECT_REASONS = ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CHARACTER_IDS,
@@ -278,9 +286,13 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   MODES,
   MODE_IDS,
   PROTOCOL_VERSION,
+  REJECT_REASONS,
   ROOM_ALPHABET,
+  SUBMISSION_KINDS,
+  SUBMISSION_STATUSES,
   gameIdForPv,
   gamesForPv,
   modesForGame,
-  normalizeWesternDigits
+  normalizeWesternDigits,
+  sanitizeName
 });

package/dist/index.d.cts

@@ -112,6 +112,14 @@ declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
  * Letters are never touched; this maps exactly twenty codepoints.
  */
 declare const normalizeWesternDigits: (s: string) => string;
+/**
+ * THE definition of "a safe player-supplied string": strip the unsafe class, normalise digits.
+ * Exported because it was being hand-copied — the relay's HTTP gates (account PATCH, question
+ * submissions) each grew their own copy of this exact body, and one of those copies stored the
+ * bidi characters LITERALLY in source, where any formatter or copy-paste could silently change
+ * what it matches. A rule that can be edited by accident is not a rule.
+ */
+declare const sanitizeName: (s: string) => string;
 declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
 declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     t: z.ZodLiteral<"createRoom">;
@@ -833,6 +841,20 @@ interface TeamView {
     avatar?: AvatarView;
 }
 interface QuestionView {
+    /** The category this question came from (gs#94 follow-up, geem-site#54). NOT reveal-gated: the
+     *  category is already on the board tile the player picked, so it gives nothing away — unlike the
+     *  id, which is a handle into the bank. It exists so «اقترح سؤال مشابه» can preset the category
+     *  instead of asking the player to re-pick it; without it a client either asks again or INFERS one,
+     *  and inferring files somebody's question under the wrong category. Optional: pre-gs#94 servers
+     *  omit it and clients must cope. */
+    categoryId?: string;
+    /** The question's id — present ONLY once revealed (gs#90). It exists so a player can say «عدّل
+     *  السؤال» about a specific question: text is neither unique (template-shaped questions collide on
+     *  wording) nor stable, so an edit identified only by its text is not reliably applicable. Kept off
+     *  the wire while the question is LIVE for the same reason `correctAnswerIndex` is — the bank is
+     *  server-side and an id is a handle into it. Optional on the wire: shipped clients ignore it, and
+     *  a client that wants it must tolerate its absence pre-reveal. */
+    id?: string;
     text: string;
     options: string[];
     hiddenOptionIndices: number[];
@@ -840,6 +862,10 @@ interface QuestionView {
     selectedAnswerIndex: number | null;
     /** Only present once revealed (anti-cheat). Null while the question is live. */
     correctAnswerIndex: number | null;
+    /** «سؤال من: …» — community submitter credit (owner ruling 2026-08-14). Present ONLY on
+     *  questions promoted from community submissions; official questions never carry it. NOT
+     *  reveal-gated — a name leaks nothing — so place it wherever it reads best. */
+    submittedBy?: string;
     /** «معلومة» — optional explanation shown AFTER the reveal. Null while the question is live (it
      *  usually names the answer — same anti-cheat gate as correctAnswerIndex) and null when the
      *  question simply has none, which is most of the bank: render the card only when non-null. */
@@ -1103,5 +1129,40 @@ type ServerMsg = {
     message: string;
     reason?: string;
 };
+/** Review states for a community submission. ⚠️ `approved` is NOT here: it is a DEPRECATED alias
+ *  written by an older geem-admin, mapped to `accepted` by the relay and permitted by 0031's CHECK
+ *  only until that write is switched. It must never become a fourth state. */
+declare const SUBMISSION_STATUSES: readonly ["pending", "accepted", "rejected"];
+type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number];
+/** A brand-new question vs a correction to one already in the bank. */
+declare const SUBMISSION_KINDS: readonly ["new", "edit"];
+type SubmissionKind = (typeof SUBMISSION_KINDS)[number];
+/** Why a submission was turned down. Blame-free by construction — the closest to "you did badly" is
+ *  `duplicate`, which is about the BANK, not the writer. Clients translate these and must fall back
+ *  to `other` on anything unrecognised, which is exactly what makes adding a seventh survivable for a
+ *  build that shipped last month and will never be updated. */
+declare const REJECT_REASONS: readonly ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
+type RejectReason = (typeof REJECT_REASONS)[number];
+/** One row of «أسئلتي». Exists as a named type so the native generator EMITS the three unions above
+ *  — quicktype only reaches what a root references, and hand-typed constants are the whole bug. */
+interface MyQuestionRow {
+    id: string;
+    status: SubmissionStatus;
+    kind: SubmissionKind;
+    text: string;
+    options: string[];
+    correctIndex: number;
+    explain: string | null;
+    createdAt: string;
+    accepted?: {
+        plays: number;
+        firstPlayedAt: string | null;
+        coins: number;
+    };
+    rejected?: {
+        reason: RejectReason;
+        canResubmit: boolean;
+    };
+}
 
-export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, type CategoryView, type CharacterId, ClientMsg, type DamaMoveView, type DamaPieceView, type DamaStateView, EMOTE_IDS, type Effect, type EmoteId, type ErsimhaStateView, GAMES, GAME_IDS, type GameId, type GameInfo, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MIN_SUPPORTED_PV, MODES, MODE_IDS, type ModeId, type ModeInfo, PROTOCOL_VERSION, type PackView, type QuestionView, ROOM_ALPHABET, type RosterEntry, type ServerMsg, type SoundName, type StrokePointView, type TeamSlotView, type TeamView, type YouContext, gameIdForPv, gamesForPv, modesForGame, normalizeWesternDigits };
+export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, type CategoryView, type CharacterId, ClientMsg, type DamaMoveView, type DamaPieceView, type DamaStateView, EMOTE_IDS, type Effect, type EmoteId, type ErsimhaStateView, GAMES, GAME_IDS, type GameId, type GameInfo, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MIN_SUPPORTED_PV, MODES, MODE_IDS, type ModeId, type ModeInfo, type MyQuestionRow, PROTOCOL_VERSION, type PackView, type QuestionView, REJECT_REASONS, ROOM_ALPHABET, type RejectReason, type RosterEntry, SUBMISSION_KINDS, SUBMISSION_STATUSES, type ServerMsg, type SoundName, type StrokePointView, type SubmissionKind, type SubmissionStatus, type TeamSlotView, type TeamView, type YouContext, gameIdForPv, gamesForPv, modesForGame, normalizeWesternDigits, sanitizeName };

package/dist/index.d.ts

@@ -112,6 +112,14 @@ declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
  * Letters are never touched; this maps exactly twenty codepoints.
  */
 declare const normalizeWesternDigits: (s: string) => string;
+/**
+ * THE definition of "a safe player-supplied string": strip the unsafe class, normalise digits.
+ * Exported because it was being hand-copied — the relay's HTTP gates (account PATCH, question
+ * submissions) each grew their own copy of this exact body, and one of those copies stored the
+ * bidi characters LITERALLY in source, where any formatter or copy-paste could silently change
+ * what it matches. A rule that can be edited by accident is not a rule.
+ */
+declare const sanitizeName: (s: string) => string;
 declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
 declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     t: z.ZodLiteral<"createRoom">;
@@ -833,6 +841,20 @@ interface TeamView {
     avatar?: AvatarView;
 }
 interface QuestionView {
+    /** The category this question came from (gs#94 follow-up, geem-site#54). NOT reveal-gated: the
+     *  category is already on the board tile the player picked, so it gives nothing away — unlike the
+     *  id, which is a handle into the bank. It exists so «اقترح سؤال مشابه» can preset the category
+     *  instead of asking the player to re-pick it; without it a client either asks again or INFERS one,
+     *  and inferring files somebody's question under the wrong category. Optional: pre-gs#94 servers
+     *  omit it and clients must cope. */
+    categoryId?: string;
+    /** The question's id — present ONLY once revealed (gs#90). It exists so a player can say «عدّل
+     *  السؤال» about a specific question: text is neither unique (template-shaped questions collide on
+     *  wording) nor stable, so an edit identified only by its text is not reliably applicable. Kept off
+     *  the wire while the question is LIVE for the same reason `correctAnswerIndex` is — the bank is
+     *  server-side and an id is a handle into it. Optional on the wire: shipped clients ignore it, and
+     *  a client that wants it must tolerate its absence pre-reveal. */
+    id?: string;
     text: string;
     options: string[];
     hiddenOptionIndices: number[];
@@ -840,6 +862,10 @@ interface QuestionView {
     selectedAnswerIndex: number | null;
     /** Only present once revealed (anti-cheat). Null while the question is live. */
     correctAnswerIndex: number | null;
+    /** «سؤال من: …» — community submitter credit (owner ruling 2026-08-14). Present ONLY on
+     *  questions promoted from community submissions; official questions never carry it. NOT
+     *  reveal-gated — a name leaks nothing — so place it wherever it reads best. */
+    submittedBy?: string;
     /** «معلومة» — optional explanation shown AFTER the reveal. Null while the question is live (it
      *  usually names the answer — same anti-cheat gate as correctAnswerIndex) and null when the
      *  question simply has none, which is most of the bank: render the card only when non-null. */
@@ -1103,5 +1129,40 @@ type ServerMsg = {
     message: string;
     reason?: string;
 };
+/** Review states for a community submission. ⚠️ `approved` is NOT here: it is a DEPRECATED alias
+ *  written by an older geem-admin, mapped to `accepted` by the relay and permitted by 0031's CHECK
+ *  only until that write is switched. It must never become a fourth state. */
+declare const SUBMISSION_STATUSES: readonly ["pending", "accepted", "rejected"];
+type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number];
+/** A brand-new question vs a correction to one already in the bank. */
+declare const SUBMISSION_KINDS: readonly ["new", "edit"];
+type SubmissionKind = (typeof SUBMISSION_KINDS)[number];
+/** Why a submission was turned down. Blame-free by construction — the closest to "you did badly" is
+ *  `duplicate`, which is about the BANK, not the writer. Clients translate these and must fall back
+ *  to `other` on anything unrecognised, which is exactly what makes adding a seventh survivable for a
+ *  build that shipped last month and will never be updated. */
+declare const REJECT_REASONS: readonly ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
+type RejectReason = (typeof REJECT_REASONS)[number];
+/** One row of «أسئلتي». Exists as a named type so the native generator EMITS the three unions above
+ *  — quicktype only reaches what a root references, and hand-typed constants are the whole bug. */
+interface MyQuestionRow {
+    id: string;
+    status: SubmissionStatus;
+    kind: SubmissionKind;
+    text: string;
+    options: string[];
+    correctIndex: number;
+    explain: string | null;
+    createdAt: string;
+    accepted?: {
+        plays: number;
+        firstPlayedAt: string | null;
+        coins: number;
+    };
+    rejected?: {
+        reason: RejectReason;
+        canResubmit: boolean;
+    };
+}
 
-export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, type CategoryView, type CharacterId, ClientMsg, type DamaMoveView, type DamaPieceView, type DamaStateView, EMOTE_IDS, type Effect, type EmoteId, type ErsimhaStateView, GAMES, GAME_IDS, type GameId, type GameInfo, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MIN_SUPPORTED_PV, MODES, MODE_IDS, type ModeId, type ModeInfo, PROTOCOL_VERSION, type PackView, type QuestionView, ROOM_ALPHABET, type RosterEntry, type ServerMsg, type SoundName, type StrokePointView, type TeamSlotView, type TeamView, type YouContext, gameIdForPv, gamesForPv, modesForGame, normalizeWesternDigits };
+export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, type CategoryView, type CharacterId, ClientMsg, type DamaMoveView, type DamaPieceView, type DamaStateView, EMOTE_IDS, type Effect, type EmoteId, type ErsimhaStateView, GAMES, GAME_IDS, type GameId, type GameInfo, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MIN_SUPPORTED_PV, MODES, MODE_IDS, type ModeId, type ModeInfo, type MyQuestionRow, PROTOCOL_VERSION, type PackView, type QuestionView, REJECT_REASONS, ROOM_ALPHABET, type RejectReason, type RosterEntry, SUBMISSION_KINDS, SUBMISSION_STATUSES, type ServerMsg, type SoundName, type StrokePointView, type SubmissionKind, type SubmissionStatus, type TeamSlotView, type TeamView, type YouContext, gameIdForPv, gamesForPv, modesForGame, normalizeWesternDigits, sanitizeName };

package/dist/index.js

@@ -39,7 +39,8 @@ var CHARACTER_IDS = ["m", "f"];
 var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 var UNSAFE_CHARS = /[\p{Cc}\u202A-\u202E\u2066-\u2069<>]/gu;
 var normalizeWesternDigits = (s) => s.replace(/[٠-٩۰-۹]/g, (d) => String("\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) >= 0 ? "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) : "\u06F0\u06F1\u06F2\u06F3\u06F4\u06F5\u06F6\u06F7\u06F8\u06F9".indexOf(d)));
-var DisplayName = z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim()).refine((s) => s.length >= 1, "name is empty after sanitizing");
+var sanitizeName = (s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim();
+var DisplayName = z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform(sanitizeName).refine((s) => s.length >= 1, "name is empty after sanitizing");
 var RoomCode = z.string().trim().toUpperCase().regex(new RegExp(`^[${ROOM_ALPHABET}]{${LIMITS.ROOM_CODE_LEN}}$`), "bad room code");
 var PlayerId = z.string().max(40);
 var HelpType = z.enum([
@@ -228,6 +229,9 @@ var ClientMsg = z.discriminatedUnion("t", [
   // Drawer passes on the served word (capped per draw-turn; relay serves a fresh one).
   z.object({ t: z.literal("skipWord") })
 ]);
+var SUBMISSION_STATUSES = ["pending", "accepted", "rejected"];
+var SUBMISSION_KINDS = ["new", "edit"];
+var REJECT_REASONS = ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
 export {
   CHARACTER_IDS,
   ClientMsg,
@@ -239,9 +243,13 @@ export {
   MODES,
   MODE_IDS,
   PROTOCOL_VERSION,
+  REJECT_REASONS,
   ROOM_ALPHABET,
+  SUBMISSION_KINDS,
+  SUBMISSION_STATUSES,
   gameIdForPv,
   gamesForPv,
   modesForGame,
-  normalizeWesternDigits
+  normalizeWesternDigits,
+  sanitizeName
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thegeem/protocol",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "Geem's wire protocol — shared zod schemas + TypeScript types for talking to the Geem game server over Socket.IO. The source of truth all clients implement against.",
   "license": "UNLICENSED",
   "homepage": "https://geem.tv",