@orakl/protocol 0.1.0

package/dist/ws-solo.schema.d.ts

@@ -0,0 +1,31 @@
+import { Schema } from "effect";
+export declare const SoloClientMessageSchema: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["auth"]>;
+    token: Schema.filter<typeof Schema.NonEmptyString>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:start"]>;
+    categoryIds: Schema.filter<Schema.Array$<typeof Schema.NonEmptyString>>;
+    timerDuration: Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+    questionCount: Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+    mode: Schema.Literal<["normal", "endless"]>;
+    difficulty: Schema.Literal<["all", "easy", "medium", "hard"]>;
+    device: Schema.optional<Schema.Literal<["mobile", "tablet", "desktop"]>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:answer"]>;
+    answerId: Schema.filter<typeof Schema.NonEmptyString>;
+    nonce: Schema.optional<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:answer-change"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:next"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:tab-blur"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:tab-focus"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:pong"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:resume"]>;
+    sessionId: Schema.filter<typeof Schema.NonEmptyString>;
+    resumeToken: Schema.optional<Schema.filter<typeof Schema.NonEmptyString>>;
+}>]>;

package/dist/ws-solo.schema.js

@@ -0,0 +1,57 @@
+import { Schema } from "effect";
+/**
+ * Frame-level validation for the solo-mode WebSocket (issue #734 hardening).
+ * One schema per `SoloClientMessage` union member in `./solo-ws.ts` —
+ * mirrors the hand-written types (no `Schema.Type` derivation feeds back into
+ * `SoloClientMessage`, see `solo-connection-handler.ts`). Keep in sync with
+ * `solo-ws.ts` whenever a frame is added/changed.
+ */
+// Tokens ride the first frame; generous cap is a DoS guard only.
+const TokenSchema = Schema.NonEmptyString.pipe(Schema.maxLength(4096));
+// DoS guard: ids that round-trip through session state.
+const BoundedIdSchema = Schema.NonEmptyString.pipe(Schema.maxLength(200));
+const SoloAuthMessageSchema = Schema.Struct({
+    type: Schema.Literal("auth"),
+    token: TokenSchema,
+});
+const SoloStartMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:start"),
+    categoryIds: Schema.Array(Schema.NonEmptyString).pipe(Schema.maxItems(50)),
+    // Plain `number` on the hand-written type (clamped to [5,120] downstream) —
+    // bounded generously here against absurd/non-finite values.
+    timerDuration: Schema.Number.pipe(Schema.finite(), Schema.greaterThan(0), Schema.lessThanOrEqualTo(600)),
+    // 0 is a valid sentinel for endless mode (draw count is uncapped downstream).
+    questionCount: Schema.Number.pipe(Schema.int(), Schema.greaterThanOrEqualTo(0), Schema.lessThanOrEqualTo(500)),
+    mode: Schema.Literal("normal", "endless"),
+    difficulty: Schema.Literal("all", "easy", "medium", "hard"),
+    device: Schema.optional(Schema.Literal("mobile", "tablet", "desktop")),
+});
+const SoloAnswerMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:answer"),
+    answerId: BoundedIdSchema,
+    nonce: Schema.optional(BoundedIdSchema),
+});
+const SoloAnswerChangeMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:answer-change"),
+});
+const SoloNextMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:next"),
+});
+const SoloTabBlurMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:tab-blur"),
+});
+const SoloTabFocusMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:tab-focus"),
+});
+const SoloPongMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:pong"),
+});
+const SoloResumeMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:resume"),
+    sessionId: BoundedIdSchema,
+    resumeToken: Schema.optional(BoundedIdSchema),
+});
+// Discriminant: Effect Schema detects the shared `type: Schema.Literal(...)`
+// field and short-circuits matching — every member needs a unique `type`.
+export const SoloClientMessageSchema = Schema.Union(SoloAuthMessageSchema, SoloStartMessageSchema, SoloAnswerMessageSchema, SoloAnswerChangeMessageSchema, SoloNextMessageSchema, SoloTabBlurMessageSchema, SoloTabFocusMessageSchema, SoloPongMessageSchema, SoloResumeMessageSchema);
+const _assertNoSoloClientMessageDrift = null;

package/dist/ws.d.ts

@@ -0,0 +1,281 @@
+import type { BadgeAward, BadgeRunParams } from "./badges.ts";
+import type { ErrorCode } from "./error-codes.ts";
+import type { AdvanceMode, Difficulty, DifficultyFilter, ScoringMode, TimerDuration } from "./game.settings.ts";
+import type { Player, PlayerRole, QuizQuestion } from "./game.ts";
+import type { GameAnswerRecord } from "./game-answer-record.ts";
+import type { MediaType, QuestionType } from "./question.schema.ts";
+import type { StreakFlourish } from "./streak-flourish.ts";
+export type ClientMessage = WsAuthMessage | PlayerAnswerMessage | PlayerEmoteMessage | PlayerRoleMessage | PlayerLeaveMessage | CuratorStartMessage | CuratorAdvanceMessage | CuratorStartRoleSelectionMessage | CuratorIntermissionMessage | CuratorPlayerActionMessage | CuratorStopMessage | CuratorResetMessage | WsPongMessage;
+/** First frame for native/display (cross-origin, no cookie): authenticates the
+ *  socket with the bearer game token (ADR 0014). Web rides the cookie instead. */
+export interface WsAuthMessage {
+    type: "auth";
+    token: string;
+}
+export interface PlayerAnswerMessage {
+    type: "player:answer";
+    answerId: string;
+    /** @deprecated identity is bound at the socket upgrade; ignored if sent. */
+    playerId?: string;
+}
+/** Player reacts after answering; positioned at the long-press/right-click point. */
+export interface PlayerEmoteMessage {
+    type: "player:emote";
+    emoteId: string;
+    offsetX: number;
+    offsetY: number;
+}
+/** Player picks a role during role selection. */
+export interface PlayerRoleMessage {
+    type: "player:role";
+    role: PlayerRole;
+}
+/** Player leaves the lobby/game voluntarily. */
+export interface PlayerLeaveMessage {
+    type: "player:leave";
+}
+/** Curator starts the game. Questions are drawn server-side from categories,
+ *  or taken from a curator-side import (preloadedQuestions). */
+export interface CuratorStartMessage {
+    type: "curator:start";
+    categoryIds?: string[];
+    timerDuration?: TimerDuration;
+    questionsPerRound?: number;
+    difficulty?: DifficultyFilter;
+    advanceMode?: AdvanceMode;
+    scoringMode?: ScoringMode;
+    preloadedQuestions?: QuizQuestion[];
+}
+export interface CuratorAdvanceMessage {
+    type: "curator:advance";
+}
+/** Curator stops the game early — remaining questions drop, the open
+ *  question miss-fills, and the game finishes on the answers given. */
+export interface CuratorStopMessage {
+    type: "curator:stop";
+}
+/** Curator sends everyone back to setup — membership drops, lobby and code
+ *  stay alive, nothing is saved. */
+export interface CuratorResetMessage {
+    type: "curator:reset";
+}
+/** Curator opens the end-of-game role-selection window. */
+export interface CuratorStartRoleSelectionMessage {
+    type: "curator:start-role-selection";
+}
+export interface CuratorIntermissionMessage {
+    type: "curator:intermission";
+    action: "start" | "end";
+}
+export interface CuratorPlayerActionMessage {
+    type: "curator:player";
+    playerId: string;
+    action: "approve" | "reject" | "remove" | "block";
+}
+/** Keepalive reply to a server game:ping (survives Cloudflare's ~100s idle WS timeout). */
+export interface WsPongMessage {
+    type: "pong";
+}
+export type ServerMessage = JoinAcceptedMessage | JoinRejectedMessage | LobbyUpdateMessage | LobbyEndedMessage | LobbyResetMessage | PlayerNicknameChangedMessage | GameStartMessage | GameQuestionMessage | GameTickMessage | PlayerAnsweredMessage | GameRoundResultMessage | GameFinalScoresMessage | GameResultsReadyMessage | RoleSelectionStartMessage | RoleSelectionUpdateMessage | RoleSelectionLockedMessage | PlayerRemovedMessage | GameIntermissionMessage | GameResumeMessage | PlayerEmoteBroadcastMessage | GameErrorMessage | GamePingMessage;
+export interface JoinAcceptedMessage {
+    type: "join:accepted";
+    playerId: string;
+    quizName: string;
+}
+export interface JoinRejectedMessage {
+    type: "join:rejected";
+    reason: string;
+}
+export interface LobbyUpdateMessage {
+    type: "lobby:update";
+    players: readonly Player[];
+    gameStarted?: boolean;
+    accessMode?: "open" | "invite-only";
+    maxPlayers?: number | null;
+    /** Curator's live-edited quiz title. */
+    quizName?: string;
+    /** Curator's live-edited quiz description. */
+    description?: string;
+    /** Curator's live-edited category list. */
+    categories?: readonly string[];
+    /** Curator's live-edited difficulty filter. */
+    difficulty?: DifficultyFilter;
+}
+export interface LobbyEndedMessage {
+    type: "lobby:ended";
+    reason?: string;
+}
+/**
+ * The game was cleared so the curator can host the next quiz ("New quiz" or
+ * "Reset to setup"): every player keeps their seat with score 0 and returns to
+ * the lobby waiting room (phase → lobby); the curator's client goes to the
+ * create page to edit the quiz.
+ */
+export interface LobbyResetMessage {
+    type: "lobby:reset";
+}
+export interface PlayerNicknameChangedMessage {
+    type: "player:nickname_changed";
+    playerId: string;
+    nickname: string;
+}
+export interface GameStartMessage {
+    type: "game:start";
+    totalQuestions: number;
+    timerDuration: TimerDuration;
+    advanceMode: AdvanceMode;
+}
+/** Question sent to players — isCorrect is omitted to prevent cheating */
+export interface PlayerQuestionAnswer {
+    id: string;
+    text: string;
+}
+export interface GameQuestionMessage {
+    type: "game:question";
+    /** The live `questions` table id — stable across the shuffle instance that
+     *  built this round's `answers[]` ids (question-flagging, ADR 0020). Never
+     *  compare answer ids across questions/games; this is the one stable
+     *  identifier for "which question is this". */
+    questionId: string;
+    questionIndex: number;
+    totalQuestions: number;
+    text: string;
+    categoryId: string;
+    difficulty?: Difficulty;
+    questionType?: QuestionType;
+    answers: PlayerQuestionAnswer[];
+    matchItems?: {
+        left: string[];
+        right: string[];
+    };
+    mediaUrl?: string;
+    mediaType?: MediaType;
+    timeRemaining: number;
+    serverTs: number;
+    /** This recipient's own already-submitted answer, if any — set only on a
+     *  snapshot replay so a mid-question (re)connect restores the locked/answered
+     *  UI instead of re-opening the question. Omitted on the live broadcast. */
+    yourAnswerId?: string;
+    /** Current answered tally, set only on a snapshot replay so the live
+     *  "N of M answered" progress survives a mid-question reconnect (otherwise it
+     *  resets to 0 until the next player:answered frame). Omitted on broadcast. */
+    answeredCount?: number;
+    answeredTotal?: number;
+}
+export interface GameTickMessage {
+    type: "game:tick";
+    timeRemaining: number;
+    serverTs: number;
+    /** Live answered tally piggybacked on the tick so players get "N of M
+     *  answered" progress without a per-answer broadcast (that stays curator/
+     *  display-only). Coarse to the 1s tick — fine for a progress cue. */
+    answeredCount?: number;
+    answeredTotal?: number;
+}
+export interface PlayerAnsweredMessage {
+    type: "player:answered";
+    playerId: string;
+    answeredCount: number;
+    totalCount: number;
+}
+export interface GameRoundResultMessage {
+    type: "game:round-result";
+    correctAnswerId: string;
+    players: Player[];
+    playerAnswers: Record<string, string>;
+    /** The curator's explanation of the answer, withheld until now (map #912,
+     *  decision 2). Omitted when the question has none. */
+    postAnswerNote?: string;
+    /** The recipient's own consecutive-correct streak and flourish — set per
+     *  connection by the transport, never broadcast, so each player sees only
+     *  their own streak (mirrors solo). */
+    yourStreak?: {
+        streak: number;
+        flourish: StreakFlourish | null;
+    };
+    /** Seconds left on the between-question countdown, carried on the
+     *  reconnect replay only, so the ring resumes where the server's advance
+     *  timer stands rather than at the full delay. */
+    countdownRemaining?: number;
+}
+export interface GameFinalScoresMessage {
+    type: "game:final-scores";
+    /** The roster as it stood at game end, roles included. Later role changes
+     *  arrive on `lobby:update` and never rewrite this list. */
+    players: Player[];
+    /** The recipient's own badges — set per-connection by the transport, never
+     *  broadcast, so each player sees only their honours (ADR 0018). */
+    yourBadges?: BadgeAward[];
+    /** Run params the client derives badge rarity from (rarity is never stored). */
+    badgeRun?: BadgeRunParams;
+    /** The recipient's own per-question answer log — set per-connection by the
+     *  transport, never broadcast, so the results page has its breakdown before
+     *  `game_results` is persisted (the persist call is fire-and-forget). */
+    yourBreakdown?: GameAnswerRecord[];
+    /** Present only when the curator stopped the game early. `served` is the
+     *  completed-question count (a round still open at the stop is dropped);
+     *  `planned` is the quiz length, which feeds history and badge floors. */
+    stopped?: {
+        served: number;
+        planned: number;
+    };
+}
+/**
+ * Broadcast once the game's `game_results` row is persisted (the persist call
+ * from `game:final-scores` is fire-and-forget, so the row may not exist yet
+ * when a results page loads on arrival). Tells a results page that loaded
+ * early to reload its row-dependent state (canFlag, alreadyFlaggedIds).
+ */
+export interface GameResultsReadyMessage {
+    type: "game:results-ready";
+}
+export interface RoleSelectionStartMessage {
+    type: "role:selection-start";
+    players: Player[];
+    timeRemaining: number;
+}
+export interface RoleSelectionUpdateMessage {
+    type: "role:selection-update";
+    players: Player[];
+    timeRemaining: number;
+}
+export interface RoleSelectionLockedMessage {
+    type: "role:selection-locked";
+    players: Player[];
+}
+export interface PlayerRemovedMessage {
+    type: "player:removed";
+    playerId: string;
+}
+export interface GameIntermissionMessage {
+    type: "game:intermission";
+    frozenTimeRemaining: number;
+}
+export interface GameResumeMessage {
+    type: "game:resume";
+    timeRemaining: number;
+}
+/** Server broadcast of a player's emote to every connected client. */
+export interface PlayerEmoteBroadcastMessage {
+    type: "player:emote";
+    playerId: string;
+    emoteId: string;
+    offsetX: number;
+    offsetY: number;
+}
+/** Server keepalive; client replies with {type:"pong"}. */
+export interface GamePingMessage {
+    type: "game:ping";
+}
+/** Failure feedback for the acting client — sent only to the socket whose
+ *  action failed (a start that drew zero questions, an answer from an
+ *  observer, a malformed frame), never broadcast. */
+export interface GameErrorMessage {
+    type: "game:error";
+    /** Machine code for the UI to map to copy. Store `ErrorCode`s plus two
+     *  transport-only codes: a frame that failed decoding, or an unexpected
+     *  server-side throw. */
+    code: ErrorCode | "invalid_message" | "internal";
+    /** Human-readable fallback when the UI has no copy for `code`. */
+    message: string;
+}

package/dist/ws.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@orakl/protocol",
+  "version": "0.1.0",
+  "description": "Orakl wire contract: WebSocket frames and API response schemas.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robcsaszar/orakl.git",
+    "directory": "packages/protocol"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "effect": "^3.22.1"
+  },
+  "devDependencies": {
+    "effect": "^3.22.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}