@thegeem/protocol 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @thegeem/protocol
+
+The **wire contract** for [Geem](https://geem.tv) — jackbox.tv-style multiplayer trivia.
+
+Shared **zod schemas + TypeScript types** for talking to the Geem game server over a
+single Socket.IO connection: `ClientMsg` in (validated), `ServerMsg` out (authoritative).
+This package is the **source of truth** every client (web + native) implements against.
+
+The server is the referee (server-authoritative): clients send *inputs* and *render* the
+authoritative state the server pushes. There is no REST gameplay API — this protocol is the
+only gate.
+
+```ts
+import { ClientMsg, ServerMsg, PROTOCOL_VERSION } from '@thegeem/protocol';
+
+// validate anything you send
+const msg = ClientMsg.parse({ t: 'joinRoom', code: 'ABCD', name: 'Sara', pv: PROTOCOL_VERSION });
+```
+
+## Versioning
+
+`PROTOCOL_VERSION` is a breaking-change counter. Clients send `pv` on entry; the server
+rejects `pv < PROTOCOL_VERSION` with `client_outdated`. The npm package version is separate
+(normal semver for the package itself).
+
+UNLICENSED — published for Geem's own clients; not for third-party use.

package/dist/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ClientMsg: () => ClientMsg,
+  GAME_IDS: () => GAME_IDS,
+  LIMITS: () => LIMITS,
+  PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  ROOM_ALPHABET: () => ROOM_ALPHABET
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("zod");
+var LIMITS = {
+  MAX_NAME_LEN: 20,
+  ROOM_CODE_LEN: 4,
+  MAX_PLAYERS: 12,
+  MAX_MSG_PER_SEC: 8
+};
+var PROTOCOL_VERSION = 1;
+var GAME_IDS = ["trivia"];
+var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
+var UNSAFE_CHARS = /[\p{Cc}<>]/gu;
+var DisplayName = import_zod.z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => s.replace(UNSAFE_CHARS, "").trim()).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([
+  "removeTwoAnswers",
+  "changeQuestion",
+  "extraTime",
+  "doublePoints",
+  "stealPoints",
+  "restPlayer",
+  "tripLevel"
+]);
+var Pv = import_zod.z.number().int().min(1).max(1e6).optional();
+var IdToken = import_zod.z.string().max(4096).optional();
+var ClientMsg = import_zod.z.discriminatedUnion("t", [
+  // room / lobby
+  import_zod.z.object({ t: import_zod.z.literal("createRoom"), name: DisplayName.optional(), pv: Pv, idToken: IdToken }),
+  import_zod.z.object({ t: import_zod.z.literal("joinRoom"), code: RoomCode, name: DisplayName, pv: Pv, idToken: IdToken }),
+  import_zod.z.object({ t: import_zod.z.literal("resume"), code: RoomCode, token: import_zod.z.string().max(120), pv: Pv, idToken: IdToken }),
+  import_zod.z.object({ t: import_zod.z.literal("leaveRoom") }),
+  import_zod.z.object({ t: import_zod.z.literal("approve"), playerId: PlayerId }),
+  import_zod.z.object({ t: import_zod.z.literal("reject"), playerId: PlayerId }),
+  import_zod.z.object({ t: import_zod.z.literal("kick"), playerId: PlayerId }),
+  // host game actions
+  import_zod.z.object({
+    t: import_zod.z.literal("startGame"),
+    game: import_zod.z.enum(GAME_IDS).optional(),
+    // which game to play; defaults to 'trivia'
+    totalRounds: import_zod.z.number().int().min(1).max(50),
+    categoryIds: import_zod.z.array(import_zod.z.string().max(60)).min(1).max(12)
+  }),
+  import_zod.z.object({ t: import_zod.z.literal("pickLevel"), categoryId: import_zod.z.string().max(60), level: import_zod.z.number().int().min(1).max(6) }),
+  import_zod.z.object({ t: import_zod.z.literal("nextTurn") }),
+  import_zod.z.object({ t: import_zod.z.literal("playAgain") }),
+  // host: after a game ends, return the SAME players to the lobby
+  import_zod.z.object({ t: import_zod.z.literal("markOpen"), correct: import_zod.z.boolean() }),
+  import_zod.z.object({ t: import_zod.z.literal("revealNoHost") }),
+  import_zod.z.object({ t: import_zod.z.literal("awardNoHost"), teamIndex: import_zod.z.number().int().min(0).max(LIMITS.MAX_PLAYERS) }),
+  import_zod.z.object({ t: import_zod.z.literal("noHostNobody") }),
+  // player actions
+  import_zod.z.object({ t: import_zod.z.literal("buzz") }),
+  import_zod.z.object({ t: import_zod.z.literal("answer"), index: import_zod.z.number().int().min(0).max(10) }),
+  import_zod.z.object({ t: import_zod.z.literal("useHelp"), helpType: HelpType }),
+  // sabotage a rival (active team only): spend a sabotage help to debuff targetTeam's next question
+  import_zod.z.object({ t: import_zod.z.literal("sabotage"), helpType: HelpType, targetTeam: import_zod.z.number().int().min(0).max(LIMITS.MAX_PLAYERS) })
+]);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ClientMsg,
+  GAME_IDS,
+  LIMITS,
+  PROTOCOL_VERSION,
+  ROOM_ALPHABET
+});

package/dist/index.d.cts

@@ -0,0 +1,396 @@
+import { z } from 'zod';
+
+/**
+ * Geem Online wire format — server-authoritative (Shape B).
+ * Clients send INPUTS (`ClientMsg`, always validated server-side); the server
+ * runs @thegeem/engine and pushes authoritative STATE (`ServerMsg`).
+ *
+ * SELF-CONTAINED: this package owns the wire contract and depends only on `zod`
+ * (no @thegeem/engine import) so it can be published publicly + generated into
+ * Swift/Kotlin. The engine re-exports these wire types and PRODUCES them.
+ */
+declare const LIMITS: {
+    readonly MAX_NAME_LEN: 20;
+    readonly ROOM_CODE_LEN: 4;
+    readonly MAX_PLAYERS: 12;
+    readonly MAX_MSG_PER_SEC: 8;
+};
+/**
+ * Wire-format generation. **Bump ONLY on a breaking change** to ClientMsg /
+ * ServerMsg / GameStateView (a field removed/renamed/retyped, or a semantic
+ * change a frozen client would mis-handle). Additive, backward-compatible
+ * changes (a new optional field, a new effect a client can ignore) do NOT bump.
+ *
+ * Why this exists: web auto-updates, but an App-Store / Play build is FROZEN on
+ * the user's device. A client sends the version it was built against (`pv`) on
+ * its first message; the server rejects `pv < PROTOCOL_VERSION` with
+ * `{ t:'error', code:'client_outdated' }` so old native builds get a clean
+ * "please update" instead of silently mis-rendering. Unversioned clients (no
+ * `pv`, e.g. the legacy web harness) are never rejected.
+ */
+declare const PROTOCOL_VERSION = 1;
+/**
+ * Geem is a PLATFORM of GAMES (jackbox-style); the trivia board is Game #1.
+ * Every room runs one game, identified by `gameId`. Add ids here as games ship.
+ * (NOTE: "modes" — controller/race/no-host — are variants WITHIN the trivia
+ *  game, not separate games. See the platform-of-games decision.)
+ */
+declare const GAME_IDS: readonly ["trivia"];
+type GameId = (typeof GAME_IDS)[number];
+/** Unambiguous room-code alphabet — no 0/O, 1/I/L. */
+declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
+declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
+declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
+    t: z.ZodLiteral<"createRoom">;
+    name: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    pv: z.ZodOptional<z.ZodNumber>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    t: "createRoom";
+    name?: string | undefined;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}, {
+    t: "createRoom";
+    name?: string | undefined;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"joinRoom">;
+    code: z.ZodString;
+    name: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    pv: z.ZodOptional<z.ZodNumber>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    t: "joinRoom";
+    name: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}, {
+    code: string;
+    t: "joinRoom";
+    name: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"resume">;
+    code: z.ZodString;
+    token: z.ZodString;
+    pv: z.ZodOptional<z.ZodNumber>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    t: "resume";
+    token: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}, {
+    code: string;
+    t: "resume";
+    token: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"leaveRoom">;
+}, "strip", z.ZodTypeAny, {
+    t: "leaveRoom";
+}, {
+    t: "leaveRoom";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"approve">;
+    playerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "approve";
+    playerId: string;
+}, {
+    t: "approve";
+    playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"reject">;
+    playerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "reject";
+    playerId: string;
+}, {
+    t: "reject";
+    playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"kick">;
+    playerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "kick";
+    playerId: string;
+}, {
+    t: "kick";
+    playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"startGame">;
+    game: z.ZodOptional<z.ZodEnum<["trivia"]>>;
+    totalRounds: z.ZodNumber;
+    categoryIds: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    t: "startGame";
+    totalRounds: number;
+    categoryIds: string[];
+    game?: "trivia" | undefined;
+}, {
+    t: "startGame";
+    totalRounds: number;
+    categoryIds: string[];
+    game?: "trivia" | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"pickLevel">;
+    categoryId: z.ZodString;
+    level: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "pickLevel";
+    categoryId: string;
+    level: number;
+}, {
+    t: "pickLevel";
+    categoryId: string;
+    level: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"nextTurn">;
+}, "strip", z.ZodTypeAny, {
+    t: "nextTurn";
+}, {
+    t: "nextTurn";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"playAgain">;
+}, "strip", z.ZodTypeAny, {
+    t: "playAgain";
+}, {
+    t: "playAgain";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"markOpen">;
+    correct: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    t: "markOpen";
+    correct: boolean;
+}, {
+    t: "markOpen";
+    correct: boolean;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"revealNoHost">;
+}, "strip", z.ZodTypeAny, {
+    t: "revealNoHost";
+}, {
+    t: "revealNoHost";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"awardNoHost">;
+    teamIndex: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "awardNoHost";
+    teamIndex: number;
+}, {
+    t: "awardNoHost";
+    teamIndex: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"noHostNobody">;
+}, "strip", z.ZodTypeAny, {
+    t: "noHostNobody";
+}, {
+    t: "noHostNobody";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"buzz">;
+}, "strip", z.ZodTypeAny, {
+    t: "buzz";
+}, {
+    t: "buzz";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"answer">;
+    index: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "answer";
+    index: number;
+}, {
+    t: "answer";
+    index: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"useHelp">;
+    helpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
+}, "strip", z.ZodTypeAny, {
+    t: "useHelp";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+}, {
+    t: "useHelp";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"sabotage">;
+    helpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
+    targetTeam: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "sabotage";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+    targetTeam: number;
+}, {
+    t: "sabotage";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+    targetTeam: number;
+}>]>;
+type ClientMsg = z.infer<typeof ClientMsg>;
+interface LobbyPlayer {
+    id: string;
+    name: string;
+    approved: boolean;
+    connected: boolean;
+}
+/** Per-recipient context attached to lobby/state pushes. */
+interface YouContext {
+    id: string;
+    isHost: boolean;
+    /** This player's team index once the game has started; null in the lobby / for the host. */
+    teamIndex: number | null;
+}
+type GameStatus = 'setup' | 'categorySelection' | 'inProgress' | 'completed';
+type GameplayFlow = 'classic' | 'openJudged' | 'noHost' | 'buzzer';
+type BuzzerGameMode = 'off' | 'solo' | 'race' | 'controller';
+/** The help/lifeline ids (same set as the inbound `HelpType` zod enum above). */
+type HelpName = z.infer<typeof HelpType>;
+type SoundName = 'correct' | 'wrong' | 'timeup' | 'warning' | 'help' | 'ding' | 'pop' | 'swoosh';
+interface TeamView {
+    id: string;
+    name: string;
+    emoji: string;
+    color: string;
+    score: number;
+    currentStreak: number;
+    /** This team's lifelines and whether each has been spent. */
+    helps: {
+        type: HelpName;
+        isUsed: boolean;
+    }[];
+}
+interface QuestionView {
+    text: string;
+    options: string[];
+    hiddenOptionIndices: number[];
+    revealed: boolean;
+    selectedAnswerIndex: number | null;
+    /** Only present once revealed (anti-cheat). Null while the question is live. */
+    correctAnswerIndex: number | null;
+    imageName?: string;
+    videoName?: string;
+}
+interface GameStateView {
+    status: GameStatus;
+    flow: GameplayFlow;
+    mode: BuzzerGameMode;
+    round: number;
+    totalRounds: number;
+    currentTeamIndex: number;
+    answeringTeamIndex: number;
+    teams: TeamView[];
+    question: QuestionView | null;
+    /** Race: the team that buzzed first (null otherwise). */
+    firstBuzzTeamIndex: number | null;
+    lockedOutTeamIndices: number[];
+    isOpenStealIntro: boolean;
+    doublePointsActive: boolean;
+    stealPointsActive: boolean;
+    trippedTeamIndices: number[];
+    /** Shared board: per category id, the level numbers already played. */
+    usedLevels: Record<string, number[]>;
+}
+/** Transient presentation effects the relay emits; clients play them once. */
+type Effect = {
+    t: 'stopTimer';
+} | {
+    t: 'startTimer';
+    duration: number;
+} | {
+    t: 'resumeTimer';
+} | {
+    t: 'addTime';
+    seconds: number;
+} | {
+    t: 'closeBuzzer';
+} | {
+    t: 'openBuzzer';
+} | {
+    t: 'serveQuestion';
+} | {
+    t: 'sound';
+    name: SoundName;
+} | {
+    t: 'reveal';
+} | {
+    t: 'celebrate';
+    hard: boolean;
+} | {
+    t: 'scorePop';
+    amount: number;
+    streakBonus: number;
+} | {
+    t: 'chargeCredit';
+} | {
+    t: 'stealPause';
+    ms: number;
+} | {
+    t: 'openStealIntro';
+    ms: number;
+} | {
+    t: 'noHostAdvance';
+    ms: number;
+} | {
+    t: 'endGame';
+};
+type ServerMsg = {
+    t: 'roomCreated';
+    code: string;
+    youId: string;
+    token: string;
+    pv: number;
+} | {
+    t: 'joinPending';
+} | {
+    t: 'joinRequest';
+    playerId: string;
+    name: string;
+} | {
+    t: 'joined';
+    youId: string;
+    token: string;
+    pv: number;
+} | {
+    t: 'joinRejected';
+    reason: string;
+} | {
+    t: 'kicked';
+} | {
+    t: 'roomClosed';
+    reason: string;
+} | {
+    t: 'lobby';
+    code: string;
+    gameId: GameId;
+    hostId: string;
+    hostName: string;
+    players: LobbyPlayer[];
+    categories: {
+        id: string;
+        name: string;
+        packId: string;
+        packName: string;
+        icon: string;
+        hasImage: boolean;
+    }[];
+    you: YouContext;
+} | {
+    t: 'state';
+    gameId: GameId;
+    view: GameStateView;
+    you: YouContext;
+    teamConnected: boolean[];
+} | {
+    t: 'fx';
+    effects: Effect[];
+} | {
+    t: 'error';
+    code: string;
+    message: string;
+};
+
+export { type BuzzerGameMode, ClientMsg, type Effect, GAME_IDS, type GameId, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, PROTOCOL_VERSION, type QuestionView, ROOM_ALPHABET, type ServerMsg, type SoundName, type TeamView, type YouContext };

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+import { z } from 'zod';
+
+/**
+ * Geem Online wire format — server-authoritative (Shape B).
+ * Clients send INPUTS (`ClientMsg`, always validated server-side); the server
+ * runs @thegeem/engine and pushes authoritative STATE (`ServerMsg`).
+ *
+ * SELF-CONTAINED: this package owns the wire contract and depends only on `zod`
+ * (no @thegeem/engine import) so it can be published publicly + generated into
+ * Swift/Kotlin. The engine re-exports these wire types and PRODUCES them.
+ */
+declare const LIMITS: {
+    readonly MAX_NAME_LEN: 20;
+    readonly ROOM_CODE_LEN: 4;
+    readonly MAX_PLAYERS: 12;
+    readonly MAX_MSG_PER_SEC: 8;
+};
+/**
+ * Wire-format generation. **Bump ONLY on a breaking change** to ClientMsg /
+ * ServerMsg / GameStateView (a field removed/renamed/retyped, or a semantic
+ * change a frozen client would mis-handle). Additive, backward-compatible
+ * changes (a new optional field, a new effect a client can ignore) do NOT bump.
+ *
+ * Why this exists: web auto-updates, but an App-Store / Play build is FROZEN on
+ * the user's device. A client sends the version it was built against (`pv`) on
+ * its first message; the server rejects `pv < PROTOCOL_VERSION` with
+ * `{ t:'error', code:'client_outdated' }` so old native builds get a clean
+ * "please update" instead of silently mis-rendering. Unversioned clients (no
+ * `pv`, e.g. the legacy web harness) are never rejected.
+ */
+declare const PROTOCOL_VERSION = 1;
+/**
+ * Geem is a PLATFORM of GAMES (jackbox-style); the trivia board is Game #1.
+ * Every room runs one game, identified by `gameId`. Add ids here as games ship.
+ * (NOTE: "modes" — controller/race/no-host — are variants WITHIN the trivia
+ *  game, not separate games. See the platform-of-games decision.)
+ */
+declare const GAME_IDS: readonly ["trivia"];
+type GameId = (typeof GAME_IDS)[number];
+/** Unambiguous room-code alphabet — no 0/O, 1/I/L. */
+declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
+declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
+declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
+    t: z.ZodLiteral<"createRoom">;
+    name: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    pv: z.ZodOptional<z.ZodNumber>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    t: "createRoom";
+    name?: string | undefined;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}, {
+    t: "createRoom";
+    name?: string | undefined;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"joinRoom">;
+    code: z.ZodString;
+    name: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    pv: z.ZodOptional<z.ZodNumber>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    t: "joinRoom";
+    name: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}, {
+    code: string;
+    t: "joinRoom";
+    name: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"resume">;
+    code: z.ZodString;
+    token: z.ZodString;
+    pv: z.ZodOptional<z.ZodNumber>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    t: "resume";
+    token: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}, {
+    code: string;
+    t: "resume";
+    token: string;
+    pv?: number | undefined;
+    idToken?: string | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"leaveRoom">;
+}, "strip", z.ZodTypeAny, {
+    t: "leaveRoom";
+}, {
+    t: "leaveRoom";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"approve">;
+    playerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "approve";
+    playerId: string;
+}, {
+    t: "approve";
+    playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"reject">;
+    playerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "reject";
+    playerId: string;
+}, {
+    t: "reject";
+    playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"kick">;
+    playerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "kick";
+    playerId: string;
+}, {
+    t: "kick";
+    playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"startGame">;
+    game: z.ZodOptional<z.ZodEnum<["trivia"]>>;
+    totalRounds: z.ZodNumber;
+    categoryIds: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    t: "startGame";
+    totalRounds: number;
+    categoryIds: string[];
+    game?: "trivia" | undefined;
+}, {
+    t: "startGame";
+    totalRounds: number;
+    categoryIds: string[];
+    game?: "trivia" | undefined;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"pickLevel">;
+    categoryId: z.ZodString;
+    level: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "pickLevel";
+    categoryId: string;
+    level: number;
+}, {
+    t: "pickLevel";
+    categoryId: string;
+    level: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"nextTurn">;
+}, "strip", z.ZodTypeAny, {
+    t: "nextTurn";
+}, {
+    t: "nextTurn";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"playAgain">;
+}, "strip", z.ZodTypeAny, {
+    t: "playAgain";
+}, {
+    t: "playAgain";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"markOpen">;
+    correct: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    t: "markOpen";
+    correct: boolean;
+}, {
+    t: "markOpen";
+    correct: boolean;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"revealNoHost">;
+}, "strip", z.ZodTypeAny, {
+    t: "revealNoHost";
+}, {
+    t: "revealNoHost";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"awardNoHost">;
+    teamIndex: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "awardNoHost";
+    teamIndex: number;
+}, {
+    t: "awardNoHost";
+    teamIndex: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"noHostNobody">;
+}, "strip", z.ZodTypeAny, {
+    t: "noHostNobody";
+}, {
+    t: "noHostNobody";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"buzz">;
+}, "strip", z.ZodTypeAny, {
+    t: "buzz";
+}, {
+    t: "buzz";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"answer">;
+    index: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "answer";
+    index: number;
+}, {
+    t: "answer";
+    index: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"useHelp">;
+    helpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
+}, "strip", z.ZodTypeAny, {
+    t: "useHelp";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+}, {
+    t: "useHelp";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"sabotage">;
+    helpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
+    targetTeam: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "sabotage";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+    targetTeam: number;
+}, {
+    t: "sabotage";
+    helpType: "removeTwoAnswers" | "changeQuestion" | "extraTime" | "doublePoints" | "stealPoints" | "restPlayer" | "tripLevel";
+    targetTeam: number;
+}>]>;
+type ClientMsg = z.infer<typeof ClientMsg>;
+interface LobbyPlayer {
+    id: string;
+    name: string;
+    approved: boolean;
+    connected: boolean;
+}
+/** Per-recipient context attached to lobby/state pushes. */
+interface YouContext {
+    id: string;
+    isHost: boolean;
+    /** This player's team index once the game has started; null in the lobby / for the host. */
+    teamIndex: number | null;
+}
+type GameStatus = 'setup' | 'categorySelection' | 'inProgress' | 'completed';
+type GameplayFlow = 'classic' | 'openJudged' | 'noHost' | 'buzzer';
+type BuzzerGameMode = 'off' | 'solo' | 'race' | 'controller';
+/** The help/lifeline ids (same set as the inbound `HelpType` zod enum above). */
+type HelpName = z.infer<typeof HelpType>;
+type SoundName = 'correct' | 'wrong' | 'timeup' | 'warning' | 'help' | 'ding' | 'pop' | 'swoosh';
+interface TeamView {
+    id: string;
+    name: string;
+    emoji: string;
+    color: string;
+    score: number;
+    currentStreak: number;
+    /** This team's lifelines and whether each has been spent. */
+    helps: {
+        type: HelpName;
+        isUsed: boolean;
+    }[];
+}
+interface QuestionView {
+    text: string;
+    options: string[];
+    hiddenOptionIndices: number[];
+    revealed: boolean;
+    selectedAnswerIndex: number | null;
+    /** Only present once revealed (anti-cheat). Null while the question is live. */
+    correctAnswerIndex: number | null;
+    imageName?: string;
+    videoName?: string;
+}
+interface GameStateView {
+    status: GameStatus;
+    flow: GameplayFlow;
+    mode: BuzzerGameMode;
+    round: number;
+    totalRounds: number;
+    currentTeamIndex: number;
+    answeringTeamIndex: number;
+    teams: TeamView[];
+    question: QuestionView | null;
+    /** Race: the team that buzzed first (null otherwise). */
+    firstBuzzTeamIndex: number | null;
+    lockedOutTeamIndices: number[];
+    isOpenStealIntro: boolean;
+    doublePointsActive: boolean;
+    stealPointsActive: boolean;
+    trippedTeamIndices: number[];
+    /** Shared board: per category id, the level numbers already played. */
+    usedLevels: Record<string, number[]>;
+}
+/** Transient presentation effects the relay emits; clients play them once. */
+type Effect = {
+    t: 'stopTimer';
+} | {
+    t: 'startTimer';
+    duration: number;
+} | {
+    t: 'resumeTimer';
+} | {
+    t: 'addTime';
+    seconds: number;
+} | {
+    t: 'closeBuzzer';
+} | {
+    t: 'openBuzzer';
+} | {
+    t: 'serveQuestion';
+} | {
+    t: 'sound';
+    name: SoundName;
+} | {
+    t: 'reveal';
+} | {
+    t: 'celebrate';
+    hard: boolean;
+} | {
+    t: 'scorePop';
+    amount: number;
+    streakBonus: number;
+} | {
+    t: 'chargeCredit';
+} | {
+    t: 'stealPause';
+    ms: number;
+} | {
+    t: 'openStealIntro';
+    ms: number;
+} | {
+    t: 'noHostAdvance';
+    ms: number;
+} | {
+    t: 'endGame';
+};
+type ServerMsg = {
+    t: 'roomCreated';
+    code: string;
+    youId: string;
+    token: string;
+    pv: number;
+} | {
+    t: 'joinPending';
+} | {
+    t: 'joinRequest';
+    playerId: string;
+    name: string;
+} | {
+    t: 'joined';
+    youId: string;
+    token: string;
+    pv: number;
+} | {
+    t: 'joinRejected';
+    reason: string;
+} | {
+    t: 'kicked';
+} | {
+    t: 'roomClosed';
+    reason: string;
+} | {
+    t: 'lobby';
+    code: string;
+    gameId: GameId;
+    hostId: string;
+    hostName: string;
+    players: LobbyPlayer[];
+    categories: {
+        id: string;
+        name: string;
+        packId: string;
+        packName: string;
+        icon: string;
+        hasImage: boolean;
+    }[];
+    you: YouContext;
+} | {
+    t: 'state';
+    gameId: GameId;
+    view: GameStateView;
+    you: YouContext;
+    teamConnected: boolean[];
+} | {
+    t: 'fx';
+    effects: Effect[];
+} | {
+    t: 'error';
+    code: string;
+    message: string;
+};
+
+export { type BuzzerGameMode, ClientMsg, type Effect, GAME_IDS, type GameId, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, PROTOCOL_VERSION, type QuestionView, ROOM_ALPHABET, type ServerMsg, type SoundName, type TeamView, type YouContext };

package/dist/index.js

@@ -0,0 +1,65 @@
+// src/index.ts
+import { z } from "zod";
+var LIMITS = {
+  MAX_NAME_LEN: 20,
+  ROOM_CODE_LEN: 4,
+  MAX_PLAYERS: 12,
+  MAX_MSG_PER_SEC: 8
+};
+var PROTOCOL_VERSION = 1;
+var GAME_IDS = ["trivia"];
+var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
+var UNSAFE_CHARS = /[\p{Cc}<>]/gu;
+var DisplayName = z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => s.replace(UNSAFE_CHARS, "").trim()).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([
+  "removeTwoAnswers",
+  "changeQuestion",
+  "extraTime",
+  "doublePoints",
+  "stealPoints",
+  "restPlayer",
+  "tripLevel"
+]);
+var Pv = z.number().int().min(1).max(1e6).optional();
+var IdToken = z.string().max(4096).optional();
+var ClientMsg = z.discriminatedUnion("t", [
+  // room / lobby
+  z.object({ t: z.literal("createRoom"), name: DisplayName.optional(), pv: Pv, idToken: IdToken }),
+  z.object({ t: z.literal("joinRoom"), code: RoomCode, name: DisplayName, pv: Pv, idToken: IdToken }),
+  z.object({ t: z.literal("resume"), code: RoomCode, token: z.string().max(120), pv: Pv, idToken: IdToken }),
+  z.object({ t: z.literal("leaveRoom") }),
+  z.object({ t: z.literal("approve"), playerId: PlayerId }),
+  z.object({ t: z.literal("reject"), playerId: PlayerId }),
+  z.object({ t: z.literal("kick"), playerId: PlayerId }),
+  // host game actions
+  z.object({
+    t: z.literal("startGame"),
+    game: z.enum(GAME_IDS).optional(),
+    // which game to play; defaults to 'trivia'
+    totalRounds: z.number().int().min(1).max(50),
+    categoryIds: z.array(z.string().max(60)).min(1).max(12)
+  }),
+  z.object({ t: z.literal("pickLevel"), categoryId: z.string().max(60), level: z.number().int().min(1).max(6) }),
+  z.object({ t: z.literal("nextTurn") }),
+  z.object({ t: z.literal("playAgain") }),
+  // host: after a game ends, return the SAME players to the lobby
+  z.object({ t: z.literal("markOpen"), correct: z.boolean() }),
+  z.object({ t: z.literal("revealNoHost") }),
+  z.object({ t: z.literal("awardNoHost"), teamIndex: z.number().int().min(0).max(LIMITS.MAX_PLAYERS) }),
+  z.object({ t: z.literal("noHostNobody") }),
+  // player actions
+  z.object({ t: z.literal("buzz") }),
+  z.object({ t: z.literal("answer"), index: z.number().int().min(0).max(10) }),
+  z.object({ t: z.literal("useHelp"), helpType: HelpType }),
+  // sabotage a rival (active team only): spend a sabotage help to debuff targetTeam's next question
+  z.object({ t: z.literal("sabotage"), helpType: HelpType, targetTeam: z.number().int().min(0).max(LIMITS.MAX_PLAYERS) })
+]);
+export {
+  ClientMsg,
+  GAME_IDS,
+  LIMITS,
+  PROTOCOL_VERSION,
+  ROOM_ALPHABET
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@thegeem/protocol",
+  "version": "0.1.0",
+  "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",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "geem",
+    "protocol",
+    "socket.io",
+    "zod"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "release": "node scripts/release.mjs"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}