@orakl/protocol 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -12,12 +12,13 @@ export * from "./pages/quiz.schema.ts";
 export type { PlayerSafeQuestion } from "./player-safe-question.ts";
 export { DifficultySchema, type ImageChoiceQuestion, type ImageMatchingQuestion, isHttpsUrl, type Media, MediaSchema, type MediaType, MediaTypeSchema, PostAnswerNoteSchema, type Question, QuestionSchema, type QuestionSource, QuestionSourceSchema, type QuestionType, QuestionTypeSchema, type Source, SourceSchema, type TextChoiceQuestion, type TrueFalseQuestion, } from "./question.schema.ts";
 export { hasMedia, isImageMatching, isTextChoice, isTrueFalse, } from "./question.ts";
+export type { QuestionRating } from "./question-rating.ts";
 export { OptionalScoringModeSchema, ScoringModeSchema, } from "./scoring.schema.ts";
-export { type SoloAnswerChangeMessage, type SoloAnswerMessage, type SoloAuthMessage, type SoloClientMessage, type SoloErrorMessage, type SoloFinalMessage, type SoloGuestLimitMessage, type SoloLifeSpentMessage, type SoloNextMessage, type SoloPingMessage, type SoloPongMessage, type SoloQuestionMessage, type SoloReadyMessage, type SoloResumeMessage, type SoloRoundResultMessage, type SoloServerMessage, type SoloStartMessage, type SoloStreakBestMessage, type SoloStreakLostMessage, type SoloStreakMessage, type SoloStreakNearMissMessage, type SoloTabBlurMessage, type SoloTabFocusMessage, type SoloTickMessage, soloError, } from "./solo-ws.ts";
+export { type SoloAnswerChangeMessage, type SoloAnswerMessage, type SoloAuthMessage, type SoloClientMessage, type SoloErrorMessage, type SoloFinalMessage, type SoloGuestLimitMessage, type SoloLifeSpentMessage, type SoloNextMessage, type SoloPingMessage, type SoloPongMessage, type SoloQuestionMessage, type SoloRateAckMessage, type SoloRateMessage, type SoloReadyMessage, type SoloResumeMessage, type SoloRoundResultMessage, type SoloServerMessage, type SoloStartMessage, type SoloStreakBestMessage, type SoloStreakLostMessage, type SoloStreakMessage, type SoloStreakNearMissMessage, type SoloTabBlurMessage, type SoloTabFocusMessage, type SoloTickMessage, soloError, } from "./solo-ws.ts";
 export type { StreakFlourish } from "./streak-flourish.ts";
 export type { LeaderboardBoard, LeaderboardDifficulty, LeaderboardScope, } from "./wire/leaderboard.ts";
 export type { OperatorQuestionRevision, PublishManyResult, QuestionRevision, } from "./wire/question-bank.ts";
 export type { FlagDetail, FlagReporter, FlagStatus, QuestionFlagAnswerSnapshot, QuestionSnapshot, } from "./wire/question-flags.ts";
-export type { ClientMessage, CuratorAdvanceMessage, CuratorIntermissionMessage, CuratorPlayerActionMessage, CuratorResetMessage, CuratorStartMessage, CuratorStartRoleSelectionMessage, CuratorStopMessage, GameErrorMessage, GameFinalScoresMessage, GameIntermissionMessage, GamePingMessage, GameQuestionMessage, GameResultsReadyMessage, GameResumeMessage, GameRoundResultMessage, GameStartMessage, GameTickMessage, JoinAcceptedMessage, JoinRejectedMessage, LobbyEndedMessage, LobbyResetMessage, LobbyUpdateMessage, PlayerAnsweredMessage, PlayerAnswerMessage, PlayerEmoteBroadcastMessage, PlayerEmoteMessage, PlayerLeaveMessage, PlayerNicknameChangedMessage, PlayerQuestionAnswer, PlayerRemovedMessage, PlayerRoleMessage, RoleSelectionLockedMessage, RoleSelectionStartMessage, RoleSelectionUpdateMessage, ServerMessage, WsAuthMessage, WsPongMessage, } from "./ws.ts";
+export type { ClientMessage, CuratorAdvanceMessage, CuratorIntermissionMessage, CuratorPlayerActionMessage, CuratorResetMessage, CuratorStartMessage, CuratorStartRoleSelectionMessage, CuratorStopMessage, GameErrorMessage, GameFinalScoresMessage, GameIntermissionMessage, GamePingMessage, GameQuestionMessage, GameResultsReadyMessage, GameResumeMessage, GameRoundResultMessage, GameStartMessage, GameTickMessage, JoinAcceptedMessage, JoinRejectedMessage, LobbyEndedMessage, LobbyResetMessage, LobbyUpdateMessage, PlayerAnsweredMessage, PlayerAnswerMessage, PlayerEmoteBroadcastMessage, PlayerEmoteMessage, PlayerLeaveMessage, PlayerNicknameChangedMessage, PlayerQuestionAnswer, PlayerRateAckMessage, PlayerRateMessage, PlayerRemovedMessage, PlayerRoleMessage, RateAckReason, RoleSelectionLockedMessage, RoleSelectionStartMessage, RoleSelectionUpdateMessage, ServerMessage, WsAuthMessage, WsPongMessage, } from "./ws.ts";
 export { ClientMessageSchema } from "./ws-game.schema.ts";
 export { SoloClientMessageSchema } from "./ws-solo.schema.ts";

package/dist/pages/app.schema.d.ts

@@ -171,6 +171,48 @@ export declare const ManageFlaggedQuestionsPageSchema: Schema.Struct<{
     statusFilter: Schema.Literal<["open", "resolved", "all"]>;
     page: typeof Schema.Number;
 }>;
+declare const QuestionRatingRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    excerpt: typeof Schema.String;
+    source: Schema.Literal<["built-in", "promoted"]>;
+    category: typeof Schema.String;
+    down: typeof Schema.Number;
+    up: typeof Schema.Number;
+    downAllTime: typeof Schema.Number;
+    upAllTime: typeof Schema.Number;
+    edited: typeof Schema.Boolean;
+    openFlags: typeof Schema.Number;
+}>;
+/** One rated question on the ratings page: counts since the last edit and all-time, no rater identity. */
+export type QuestionRatingRow = typeof QuestionRatingRowSchema.Type;
+/** Body of `GET /api/pages/manage/question-ratings`. */
+export declare const ManageQuestionRatingsPageSchema: Schema.Struct<{
+    initial: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly source: "built-in" | "promoted";
+        readonly id: string;
+        readonly up: number;
+        readonly category: string;
+        readonly excerpt: string;
+        readonly down: number;
+        readonly downAllTime: number;
+        readonly upAllTime: number;
+        readonly edited: boolean;
+        readonly openFlags: number;
+    }, {
+        readonly source: "built-in" | "promoted";
+        readonly id: string;
+        readonly up: number;
+        readonly category: string;
+        readonly excerpt: string;
+        readonly down: number;
+        readonly downAllTime: number;
+        readonly upAllTime: number;
+        readonly edited: boolean;
+        readonly openFlags: number;
+    }, never>>>;
+    initialHasMore: typeof Schema.Boolean;
+    page: typeof Schema.Number;
+}>;
 declare const AuthoredQuestionRowSchema: Schema.Struct<{
     id: typeof Schema.String;
     category: typeof Schema.String;
@@ -469,11 +511,23 @@ export declare const CuratorQuestionsPageSchema: Schema.Struct<{
         readonly label: string;
         readonly category: string;
         readonly created_at: string;
+        readonly ratings?: {
+            readonly up: number;
+            readonly down: number;
+            readonly downAllTime: number;
+            readonly upAllTime: number;
+        } | undefined;
     }, {
         readonly id: string;
         readonly label: string;
         readonly category: string;
         readonly created_at: string;
+        readonly ratings?: {
+            readonly up: number;
+            readonly down: number;
+            readonly downAllTime: number;
+            readonly upAllTime: number;
+        } | undefined;
     }, never>>>;
     questionsCursor: Schema.NullOr<typeof Schema.String>;
 }>;

package/dist/pages/app.schema.js

@@ -137,6 +137,24 @@ export const ManageFlaggedQuestionsPageSchema = Schema.Struct({
     statusFilter: Schema.Literal("open", "resolved", "all"),
     page: Schema.Number,
 });
+const QuestionRatingRowSchema = Schema.Struct({
+    id: Schema.String,
+    excerpt: Schema.String,
+    source: Schema.Literal("built-in", "promoted"),
+    category: Schema.String,
+    down: Schema.Number,
+    up: Schema.Number,
+    downAllTime: Schema.Number,
+    upAllTime: Schema.Number,
+    edited: Schema.Boolean,
+    openFlags: Schema.Number,
+});
+/** Body of `GET /api/pages/manage/question-ratings`. */
+export const ManageQuestionRatingsPageSchema = Schema.Struct({
+    initial: Arr(QuestionRatingRowSchema),
+    initialHasMore: Schema.Boolean,
+    page: Schema.Number,
+});
 const AuthoredQuestionRowSchema = Schema.Struct({
     id: Schema.String,
     category: Schema.String,
@@ -293,6 +311,13 @@ const OwnQuestionSchema = Schema.Struct({
     category: Schema.String,
     label: Schema.String,
     created_at: Schema.String,
+    /** Thumbs counts since the last edit and all-time; absent with the rating flag off. */
+    ratings: Schema.optional(Schema.Struct({
+        up: Schema.Number,
+        down: Schema.Number,
+        upAllTime: Schema.Number,
+        downAllTime: Schema.Number,
+    })),
 });
 /** Body of `GET /api/pages/curator/questions`. */
 export const CuratorQuestionsPageSchema = Schema.Struct({

package/dist/pages/quiz.schema.d.ts

@@ -41,6 +41,7 @@ export declare const LayoutPageSchema: Schema.Struct<{
         readonly IMAGE_QUIZ_CATEGORY?: boolean | undefined;
         readonly BADGE_DISPLAY?: boolean | undefined;
         readonly ROLE_SELECTION?: boolean | undefined;
+        readonly QUESTION_RATING?: boolean | undefined;
     }, {
         readonly FEEDBACK_WIDGET?: boolean | undefined;
         readonly ENABLE_IMPORTS?: boolean | undefined;
@@ -54,6 +55,7 @@ export declare const LayoutPageSchema: Schema.Struct<{
         readonly IMAGE_QUIZ_CATEGORY?: boolean | undefined;
         readonly BADGE_DISPLAY?: boolean | undefined;
         readonly ROLE_SELECTION?: boolean | undefined;
+        readonly QUESTION_RATING?: boolean | undefined;
     }, never>;
 }>;
 declare const PlayerJourneySchema: Schema.Struct<{

package/dist/pages/quiz.schema.js

@@ -45,6 +45,7 @@ const UiFlagsSchema = Schema.partial(Schema.Struct({
     IMAGE_QUIZ_CATEGORY: Schema.Boolean,
     BADGE_DISPLAY: Schema.Boolean,
     ROLE_SELECTION: Schema.Boolean,
+    QUESTION_RATING: Schema.Boolean,
 }));
 /** Body of `GET /api/layout`. */
 export const LayoutPageSchema = Schema.Struct({

package/dist/question-rating.d.ts

@@ -0,0 +1,2 @@
+/** A Question rating's thumb: `"up"` is "Good question", `"down"` is "Bad question". */
+export type QuestionRating = "up" | "down";

package/dist/question-rating.js

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

package/dist/solo-ws.d.ts

@@ -1,6 +1,8 @@
 import type { BadgeAward } from "./badges.ts";
 import type { PlayerSafeQuestion } from "./player-safe-question.ts";
 import type { MediaType, QuestionSource } from "./question.ts";
+import type { QuestionRating } from "./question-rating.ts";
+import type { RateAckReason } from "./ws.ts";
 export type SoloAuthMessage = {
     type: "auth";
     token: string;
@@ -47,7 +49,16 @@ export type SoloResumeMessage = {
     /** Secret issued in solo:ready; required to resume a guest session (anti-hijack). */
     resumeToken?: string;
 };
-export type SoloClientMessage = SoloAuthMessage | SoloStartMessage | SoloAnswerMessage | SoloAnswerChangeMessage | SoloNextMessage | SoloTabBlurMessage | SoloTabFocusMessage | SoloPongMessage | SoloResumeMessage;
+/** Rate a question revealed in this run (signed-in runs only). The server
+ *  answers with `solo:rate-ack` echoing `questionId`; `reason: "disabled"`
+ *  when the rating flag is off. */
+export type SoloRateMessage = {
+    type: "solo:rate";
+    /** Bank question id, as on `solo:question`. */
+    questionId: string;
+    rating: QuestionRating;
+};
+export type SoloClientMessage = SoloAuthMessage | SoloStartMessage | SoloAnswerMessage | SoloAnswerChangeMessage | SoloNextMessage | SoloTabBlurMessage | SoloTabFocusMessage | SoloPongMessage | SoloResumeMessage | SoloRateMessage;
 export type SoloReadyMessage = {
     type: "solo:ready";
     isGuest: boolean;
@@ -199,4 +210,13 @@ export type SoloGuestLimitMessage = {
     reason: string;
     upgradeHint: string;
 };
-export type SoloServerMessage = SoloReadyMessage | SoloQuestionMessage | SoloTickMessage | SoloRoundResultMessage | SoloStreakMessage | SoloStreakLostMessage | SoloStreakNearMissMessage | SoloStreakBestMessage | SoloLifeSpentMessage | SoloFinalMessage | SoloPingMessage | SoloErrorMessage | SoloGuestLimitMessage;
+/** Outcome of one `solo:rate`: `ok` is false when the rating was refused or
+ *  not stored. Failures ride here, never on `solo:error`. */
+export type SoloRateAckMessage = {
+    type: "solo:rate-ack";
+    questionId: string;
+    ok: boolean;
+    /** Set when the server refuses every rating because the flag is off. */
+    reason?: RateAckReason;
+};
+export type SoloServerMessage = SoloReadyMessage | SoloQuestionMessage | SoloTickMessage | SoloRoundResultMessage | SoloStreakMessage | SoloStreakLostMessage | SoloStreakNearMissMessage | SoloStreakBestMessage | SoloLifeSpentMessage | SoloFinalMessage | SoloPingMessage | SoloErrorMessage | SoloGuestLimitMessage | SoloRateAckMessage;

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

@@ -16,6 +16,10 @@ export declare const ClientMessageSchema: Schema.Union<[Schema.Struct<{
     role: Schema.Literal<["player", "observer"]>;
 }>, Schema.Struct<{
     type: Schema.Literal<["player:leave"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["player:rate"]>;
+    questionId: Schema.filter<typeof Schema.NonEmptyString>;
+    rating: Schema.Literal<["up", "down"]>;
 }>, Schema.Struct<{
     type: Schema.Literal<["curator:start"]>;
     categoryIds: Schema.optional<Schema.filter<Schema.Array$<typeof Schema.NonEmptyString>>>;

package/dist/ws-game.schema.js

@@ -45,6 +45,11 @@ const PlayerRoleMessageSchema = Schema.Struct({
 const PlayerLeaveMessageSchema = Schema.Struct({
     type: Schema.Literal("player:leave"),
 });
+const PlayerRateMessageSchema = Schema.Struct({
+    type: Schema.Literal("player:rate"),
+    questionId: BoundedIdSchema,
+    rating: Schema.Literal("up", "down"),
+});
 // ─── curator:* ──────────────────────────────────────────────────────────────
 // QuestionType minus "image_matching" (mirrors StandardQuizQuestion).
 const StandardQuizQuestionTypeSchema = Schema.Literal("text_choice", "image_choice", "true_false", "finish_line", "audio_identify", "sequence_order", "estimate_range", "fill_blank", "matching_pairs", "progressive_reveal");
@@ -127,5 +132,5 @@ const WsPongMessageSchema = Schema.Struct({
 });
 // Discriminant: Effect Schema detects the shared `type: Schema.Literal(...)`
 // field and short-circuits matching — every member needs a unique `type`.
-export const ClientMessageSchema = Schema.Union(WsAuthMessageSchema, PlayerAnswerMessageSchema, PlayerEmoteMessageSchema, PlayerRoleMessageSchema, PlayerLeaveMessageSchema, CuratorStartMessageSchema, CuratorAdvanceMessageSchema, CuratorStartRoleSelectionMessageSchema, CuratorIntermissionMessageSchema, CuratorPlayerActionMessageSchema, CuratorStopMessageSchema, CuratorResetMessageSchema, WsPongMessageSchema);
+export const ClientMessageSchema = Schema.Union(WsAuthMessageSchema, PlayerAnswerMessageSchema, PlayerEmoteMessageSchema, PlayerRoleMessageSchema, PlayerLeaveMessageSchema, PlayerRateMessageSchema, CuratorStartMessageSchema, CuratorAdvanceMessageSchema, CuratorStartRoleSelectionMessageSchema, CuratorIntermissionMessageSchema, CuratorPlayerActionMessageSchema, CuratorStopMessageSchema, CuratorResetMessageSchema, WsPongMessageSchema);
 const _assertNoClientMessageDrift = null;

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

@@ -28,4 +28,8 @@ export declare const SoloClientMessageSchema: Schema.Union<[Schema.Struct<{
     type: Schema.Literal<["solo:resume"]>;
     sessionId: Schema.filter<typeof Schema.NonEmptyString>;
     resumeToken: Schema.optional<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["solo:rate"]>;
+    questionId: Schema.filter<typeof Schema.NonEmptyString>;
+    rating: Schema.Literal<["up", "down"]>;
 }>]>;

package/dist/ws-solo.schema.js

@@ -51,7 +51,12 @@ const SoloResumeMessageSchema = Schema.Struct({
     sessionId: BoundedIdSchema,
     resumeToken: Schema.optional(BoundedIdSchema),
 });
+const SoloRateMessageSchema = Schema.Struct({
+    type: Schema.Literal("solo:rate"),
+    questionId: BoundedIdSchema,
+    rating: Schema.Literal("up", "down"),
+});
 // 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);
+export const SoloClientMessageSchema = Schema.Union(SoloAuthMessageSchema, SoloStartMessageSchema, SoloAnswerMessageSchema, SoloAnswerChangeMessageSchema, SoloNextMessageSchema, SoloTabBlurMessageSchema, SoloTabFocusMessageSchema, SoloPongMessageSchema, SoloResumeMessageSchema, SoloRateMessageSchema);
 const _assertNoSoloClientMessageDrift = null;

package/dist/ws.d.ts

@@ -4,8 +4,9 @@ import type { AdvanceMode, Difficulty, DifficultyFilter, ScoringMode, TimerDurat
 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 { QuestionRating } from "./question-rating.ts";
 import type { StreakFlourish } from "./streak-flourish.ts";
-export type ClientMessage = WsAuthMessage | PlayerAnswerMessage | PlayerEmoteMessage | PlayerRoleMessage | PlayerLeaveMessage | CuratorStartMessage | CuratorAdvanceMessage | CuratorStartRoleSelectionMessage | CuratorIntermissionMessage | CuratorPlayerActionMessage | CuratorStopMessage | CuratorResetMessage | WsPongMessage;
+export type ClientMessage = WsAuthMessage | PlayerAnswerMessage | PlayerEmoteMessage | PlayerRoleMessage | PlayerLeaveMessage | PlayerRateMessage | 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 {
@@ -34,6 +35,15 @@ export interface PlayerRoleMessage {
 export interface PlayerLeaveMessage {
     type: "player:leave";
 }
+/** Rate a question revealed in this game — from a signed-in player who played
+ *  its round, or the curator. The server answers with `player:rate-ack`
+ *  echoing `questionId`; `reason: "disabled"` when the rating flag is off. */
+export interface PlayerRateMessage {
+    type: "player:rate";
+    /** Bank question id, as on `game:question`. */
+    questionId: string;
+    rating: QuestionRating;
+}
 /** Curator starts the game. Questions are drawn server-side from categories,
  *  or taken from a curator-side import (preloadedQuestions). */
 export interface CuratorStartMessage {
@@ -76,7 +86,7 @@ export interface CuratorPlayerActionMessage {
 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 type ServerMessage = JoinAcceptedMessage | JoinRejectedMessage | LobbyUpdateMessage | LobbyEndedMessage | LobbyResetMessage | PlayerNicknameChangedMessage | GameStartMessage | GameQuestionMessage | GameTickMessage | PlayerAnsweredMessage | GameRoundResultMessage | GameFinalScoresMessage | GameResultsReadyMessage | RoleSelectionStartMessage | RoleSelectionUpdateMessage | RoleSelectionLockedMessage | PlayerRemovedMessage | GameIntermissionMessage | GameResumeMessage | PlayerEmoteBroadcastMessage | GameErrorMessage | GamePingMessage | PlayerRateAckMessage;
 export interface JoinAcceptedMessage {
     type: "join:accepted";
     playerId: string;
@@ -279,3 +289,15 @@ export interface GameErrorMessage {
     /** Human-readable fallback when the UI has no copy for `code`. */
     message: string;
 }
+/** Why a rate ack failed for every rating alike: the flag is off. */
+export type RateAckReason = "disabled";
+/** Outcome of one `player:rate`, to the rater only: `ok` is false when the
+ *  rating was refused or not stored. Failures ride here, never on
+ *  `game:error`, which carries no request id. */
+export interface PlayerRateAckMessage {
+    type: "player:rate-ack";
+    questionId: string;
+    ok: boolean;
+    /** Set when the server refuses every rating because the flag is off. */
+    reason?: RateAckReason;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orakl/protocol",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Orakl wire contract: WebSocket frames and API response schemas.",
   "license": "AGPL-3.0-only",
   "repository": {