@orakl/protocol 0.4.0 → 0.7.0

package/dist/error-codes.d.ts

@@ -1 +1 @@
-export type ErrorCode = "no_active_lobby" | "no_active_game" | "device_blocked" | "nickname_taken" | "device_in_lobby" | "player_not_found" | "player_not_pending" | "intermission_invalid_phase" | "not_in_intermission" | "category_name_exists" | "category_not_found" | "category_has_questions" | "user_not_found" | "curation_request_pending" | "curator_self_join" | "already_flagged" | "question_not_found" | "invalid_answer" | "game_in_progress" | "already_answered" | "observer_forbidden" | "no_questions" | "no_categories" | "too_few_players" | "hosting_closed" | "not_answered" | "flag_not_toggleable" | "solo_invalid_phase" | "solo_invalid_answer" | "solo_nonce_mismatch" | "solo_answer_expired" | "solo_guest_limit" | "solo_no_questions" | "solo_resume_denied" | "solo_auth_failed";
+export type ErrorCode = "no_active_lobby" | "no_active_game" | "device_blocked" | "nickname_taken" | "device_in_lobby" | "player_not_found" | "player_not_pending" | "intermission_invalid_phase" | "not_in_intermission" | "category_name_exists" | "category_not_found" | "category_has_questions" | "tag_name_exists" | "tag_not_found" | "tag_has_questions" | "tag_in_season" | "category_in_season" | "season_name_exists" | "season_not_found" | "user_not_found" | "curation_request_pending" | "curator_self_join" | "already_flagged" | "question_not_found" | "invalid_answer" | "game_in_progress" | "already_answered" | "observer_forbidden" | "no_questions" | "season_out_of_season" | "no_categories" | "too_few_players" | "hosting_closed" | "not_answered" | "flag_not_toggleable" | "solo_invalid_phase" | "solo_invalid_answer" | "solo_nonce_mismatch" | "solo_answer_expired" | "solo_guest_limit" | "solo_no_questions" | "solo_season_out_of_season" | "solo_resume_denied" | "solo_auth_failed";

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

@@ -125,6 +125,45 @@ declare const CategorySchema: Schema.Struct<{
     question_count: typeof Schema.Number;
 }>;
 export type Category = typeof CategorySchema.Type;
+declare const TagSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    /** Questions whose `metadata.tags` carries this name. */
+    question_count: typeof Schema.Number;
+}>;
+export type Tag = typeof TagSchema.Type;
+declare const SeasonSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    description: Schema.NullOr<typeof Schema.String>;
+    icon: Schema.NullOr<typeof Schema.String>;
+    color: Schema.NullOr<typeof Schema.String>;
+    /** `window_start`/`window_end` are `MM-DD` when true, `YYYY-MM-DD` when false. */
+    repeats_yearly: typeof Schema.Boolean;
+    window_start: typeof Schema.String;
+    window_end: typeof Schema.String;
+    /** Member `categories.id` values. */
+    category_ids: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+    /** Member tag names. */
+    tag_names: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+    /** Distinct questions reachable through the member categories and tags. */
+    pool_size: typeof Schema.Number;
+}>;
+export type Season = typeof SeasonSchema.Type;
+/** A Season as the play pickers offer it: selectable in its window, locked with its opening day outside. */
+export declare const SeasonOptionSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    icon: Schema.NullOr<typeof Schema.String>;
+    color: Schema.NullOr<typeof Schema.String>;
+    /** Distinct questions reachable through the Season's categories and Tags. */
+    count: typeof Schema.Number;
+    /** True outside the window; a locked Season cannot be picked. */
+    locked: typeof Schema.Boolean;
+    /** Next day the window opens (`YYYY-MM-DD`), only while locked. */
+    opensOn: Schema.NullOr<typeof Schema.String>;
+}>;
+export type SeasonOption = typeof SeasonOptionSchema.Type;
 /** Body of `GET /api/pages/manage/categories`. */
 export declare const ManageCategoriesPageSchema: Schema.Struct<{
     initial: Schema.mutable<Schema.Array$<Schema.Schema<{
@@ -142,6 +181,40 @@ export declare const ManageCategoriesPageSchema: Schema.Struct<{
         readonly icon: string | null;
         readonly question_count: number;
     }, never>>>;
+    tags: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly name: string;
+        readonly id: string;
+        readonly question_count: number;
+    }, {
+        readonly name: string;
+        readonly id: string;
+        readonly question_count: number;
+    }, never>>>;
+    seasons: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly name: string;
+        readonly id: string;
+        readonly color: string | null;
+        readonly description: string | null;
+        readonly icon: string | null;
+        readonly repeats_yearly: boolean;
+        readonly window_start: string;
+        readonly window_end: string;
+        readonly category_ids: string[];
+        readonly tag_names: string[];
+        readonly pool_size: number;
+    }, {
+        readonly name: string;
+        readonly id: string;
+        readonly color: string | null;
+        readonly description: string | null;
+        readonly icon: string | null;
+        readonly repeats_yearly: boolean;
+        readonly window_start: string;
+        readonly window_end: string;
+        readonly category_ids: string[];
+        readonly tag_names: string[];
+        readonly pool_size: number;
+    }, never>>>;
 }>;
 declare const AdminFlagRowSchema: Schema.Struct<{
     questionId: typeof Schema.String;
@@ -307,6 +380,7 @@ declare const QuizPresetSchema: Schema.Struct<{
     name: typeof Schema.String;
     description: Schema.NullOr<typeof Schema.String>;
     category_ids: typeof Schema.String;
+    season_ids: typeof Schema.String;
     timer_duration: typeof Schema.Number;
     questions_per_round: typeof Schema.Number;
     difficulty: typeof Schema.String;
@@ -317,8 +391,41 @@ declare const QuizPresetSchema: Schema.Struct<{
     created_at: typeof Schema.String;
 }>;
 export type QuizPreset = typeof QuizPresetSchema.Type;
+/** What stopped a saved Quiz's members from drawing: closed or gone Seasons, gone or hidden categories. */
+declare const PresetMarksSchema: Schema.Struct<{
+    closedSeasons: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly name: string;
+        readonly id: string;
+        readonly opensOn: string | null;
+    }, {
+        readonly name: string;
+        readonly id: string;
+        readonly opensOn: string | null;
+    }, never>>>;
+    missingSeasons: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+    missingCategories: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+    hiddenCategories: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+}>;
+export type PresetMarks = typeof PresetMarksSchema.Type;
 /** Body of `GET /api/pages/curator/create`. */
 export declare const CuratorCreatePageSchema: Schema.Struct<{
+    seasons: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly name: string;
+        readonly count: number;
+        readonly id: string;
+        readonly color: string | null;
+        readonly icon: string | null;
+        readonly locked: boolean;
+        readonly opensOn: string | null;
+    }, {
+        readonly name: string;
+        readonly count: number;
+        readonly id: string;
+        readonly color: string | null;
+        readonly icon: string | null;
+        readonly locked: boolean;
+        readonly opensOn: string | null;
+    }, never>>>;
     categories: Schema.mutable<Schema.Array$<Schema.Schema<{
         readonly name: string;
         readonly count: number;
@@ -339,8 +446,9 @@ export declare const CuratorCreatePageSchema: Schema.Struct<{
         readonly description: string | null;
         readonly difficulty: string;
         readonly created_at: string;
-        readonly curator_id: string;
         readonly category_ids: string;
+        readonly curator_id: string;
+        readonly season_ids: string;
         readonly timer_duration: number;
         readonly questions_per_round: number;
         readonly advance_mode: string;
@@ -353,8 +461,9 @@ export declare const CuratorCreatePageSchema: Schema.Struct<{
         readonly description: string | null;
         readonly difficulty: string;
         readonly created_at: string;
-        readonly curator_id: string;
         readonly category_ids: string;
+        readonly curator_id: string;
+        readonly season_ids: string;
         readonly timer_duration: number;
         readonly questions_per_round: number;
         readonly advance_mode: string;
@@ -362,6 +471,20 @@ export declare const CuratorCreatePageSchema: Schema.Struct<{
         readonly access_mode: string;
         readonly max_players: number | null;
     }, never>>>;
+    presetMarks: Schema.Record$<typeof Schema.String, Schema.Struct<{
+        closedSeasons: Schema.mutable<Schema.Array$<Schema.Schema<{
+            readonly name: string;
+            readonly id: string;
+            readonly opensOn: string | null;
+        }, {
+            readonly name: string;
+            readonly id: string;
+            readonly opensOn: string | null;
+        }, never>>>;
+        missingSeasons: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+        missingCategories: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+        hiddenCategories: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+    }>>;
     presetLimit: typeof Schema.Number;
     subscription: Schema.NullOr<Schema.Struct<{
         user_id: typeof Schema.String;
@@ -389,6 +512,7 @@ export declare const CuratorHistoryPageSchema: Schema.Struct<{
         readonly started_at: string;
         readonly player_count: number;
         readonly total_questions: number;
+        readonly seasonNames: string[];
         readonly winners: string[];
         readonly top_score: number | null;
     }, {
@@ -397,6 +521,7 @@ export declare const CuratorHistoryPageSchema: Schema.Struct<{
         readonly started_at: string;
         readonly player_count: number;
         readonly total_questions: number;
+        readonly seasonNames: string[];
         readonly winners: string[];
         readonly top_score: number | null;
     }, never>>>;
@@ -419,6 +544,8 @@ export declare const CuratorHistoryEntryPageSchema: Schema.Struct<{
             started_at: typeof Schema.String;
             ended_at: Schema.NullOr<typeof Schema.String>;
             categoryIds: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+            seasonIds: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+            seasonNames: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
             timer_duration: typeof Schema.Number;
             total_questions: typeof Schema.Number;
             player_count: typeof Schema.Number;
@@ -530,6 +657,8 @@ export declare const CuratorQuestionsPageSchema: Schema.Struct<{
         } | undefined;
     }, never>>>;
     questionsCursor: Schema.NullOr<typeof Schema.String>;
+    /** Admin-defined tag names, sorted. */
+    tags: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
 }>;
 /** Body of `GET /api/pages/solo/layout`. */
 export declare const SoloLayoutPageSchema: Schema.Struct<{
@@ -539,6 +668,7 @@ export declare const SoloLayoutPageSchema: Schema.Struct<{
     nickname: typeof Schema.String;
     profileAvatarSrc: typeof Schema.String;
     categoryDataJson: typeof Schema.String;
+    seasonDataJson: typeof Schema.String;
 }>;
 declare const LeaderboardEntrySchema: Schema.Struct<{
     rank: typeof Schema.Number;
@@ -576,8 +706,10 @@ export declare const SoloLeaderboardPageSchema: Schema.Struct<{
         readonly completed_at: number;
     }, never>>>;
     board: Schema.Literal<["score", "streak", "accuracy", "speed", "survival"]>;
-    scope: Schema.Literal<["all-time", "daily", "weekly", "monthly"]>;
+    scope: Schema.Literal<["all-time", "daily", "weekly", "monthly", "season"]>;
     categoryId: Schema.NullOr<typeof Schema.String>;
+    seasonId: Schema.NullOr<typeof Schema.String>;
+    opening: Schema.NullOr<typeof Schema.String>;
     difficulty: Schema.NullOr<Schema.Literal<["easy", "medium", "hard"]>>;
     categories: Schema.mutable<Schema.Array$<Schema.Schema<{
         readonly name: string;
@@ -586,6 +718,19 @@ export declare const SoloLeaderboardPageSchema: Schema.Struct<{
         readonly name: string;
         readonly id: string;
     }, never>>>;
+    seasonBoards: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly name: string;
+        readonly label: string;
+        readonly current: boolean;
+        readonly seasonId: string;
+        readonly opening: string;
+    }, {
+        readonly name: string;
+        readonly label: string;
+        readonly current: boolean;
+        readonly seasonId: string;
+        readonly opening: string;
+    }, never>>>;
     userRank: Schema.NullOr<typeof Schema.Number>;
     eligibleCount: typeof Schema.Number;
     percentile: Schema.NullOr<typeof Schema.Number>;

package/dist/pages/app.schema.js

@@ -119,9 +119,47 @@ const CategorySchema = Schema.Struct({
     color: Schema.NullOr(Schema.String),
     question_count: Schema.Number,
 });
+const TagSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    /** Questions whose `metadata.tags` carries this name. */
+    question_count: Schema.Number,
+});
+const SeasonSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    description: Schema.NullOr(Schema.String),
+    icon: Schema.NullOr(Schema.String),
+    color: Schema.NullOr(Schema.String),
+    /** `window_start`/`window_end` are `MM-DD` when true, `YYYY-MM-DD` when false. */
+    repeats_yearly: Schema.Boolean,
+    window_start: Schema.String,
+    window_end: Schema.String,
+    /** Member `categories.id` values. */
+    category_ids: Arr(Schema.String),
+    /** Member tag names. */
+    tag_names: Arr(Schema.String),
+    /** Distinct questions reachable through the member categories and tags. */
+    pool_size: Schema.Number,
+});
+/** A Season as the play pickers offer it: selectable in its window, locked with its opening day outside. */
+export const SeasonOptionSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    icon: Schema.NullOr(Schema.String),
+    color: Schema.NullOr(Schema.String),
+    /** Distinct questions reachable through the Season's categories and Tags. */
+    count: Schema.Number,
+    /** True outside the window; a locked Season cannot be picked. */
+    locked: Schema.Boolean,
+    /** Next day the window opens (`YYYY-MM-DD`), only while locked. */
+    opensOn: Schema.NullOr(Schema.String),
+});
 /** Body of `GET /api/pages/manage/categories`. */
 export const ManageCategoriesPageSchema = Schema.Struct({
     initial: Arr(CategorySchema),
+    tags: Arr(TagSchema),
+    seasons: Arr(SeasonSchema),
 });
 const AdminFlagRowSchema = Schema.Struct({
     questionId: Schema.String,
@@ -210,6 +248,7 @@ const QuizPresetSchema = Schema.Struct({
     name: Schema.String,
     description: Schema.NullOr(Schema.String),
     category_ids: Schema.String,
+    season_ids: Schema.String,
     timer_duration: Schema.Number,
     questions_per_round: Schema.Number,
     difficulty: Schema.String,
@@ -219,11 +258,24 @@ const QuizPresetSchema = Schema.Struct({
     max_players: Schema.NullOr(Schema.Number),
     created_at: Schema.String,
 });
+/** What stopped a saved Quiz's members from drawing: closed or gone Seasons, gone or hidden categories. */
+const PresetMarksSchema = Schema.Struct({
+    closedSeasons: Arr(Schema.Struct({
+        id: Schema.String,
+        name: Schema.String,
+        opensOn: Schema.NullOr(Schema.String),
+    })),
+    missingSeasons: Arr(Schema.String),
+    missingCategories: Arr(Schema.String),
+    hiddenCategories: Arr(Schema.String),
+});
 /** Body of `GET /api/pages/curator/create`. */
 export const CuratorCreatePageSchema = Schema.Struct({
+    seasons: Arr(SeasonOptionSchema),
     categories: Arr(CategoryOptionSchema),
     categoryColors: Schema.Record({ key: Schema.String, value: Schema.String }),
     presets: Arr(QuizPresetSchema),
+    presetMarks: Schema.Record({ key: Schema.String, value: PresetMarksSchema }),
     presetLimit: Schema.Number,
     subscription: Schema.NullOr(SubscriptionRowSchema),
     allowance: HostingAllowanceSchema,
@@ -234,6 +286,7 @@ const GameHistoryListItemSchema = Schema.Struct({
     started_at: Schema.String,
     player_count: Schema.Number,
     total_questions: Schema.Number,
+    seasonNames: Arr(Schema.String),
     winners: Arr(Schema.String),
     top_score: Schema.NullOr(Schema.Number),
 });
@@ -248,6 +301,8 @@ const GameHistoryEntrySchema = Schema.Struct({
     started_at: Schema.String,
     ended_at: Schema.NullOr(Schema.String),
     categoryIds: Arr(Schema.String),
+    seasonIds: Arr(Schema.String),
+    seasonNames: Arr(Schema.String),
     timer_duration: Schema.Number,
     total_questions: Schema.Number,
     player_count: Schema.Number,
@@ -324,6 +379,8 @@ export const CuratorQuestionsPageSchema = Schema.Struct({
     categories: Arr(CuratorQuestionsCategoryOptionSchema),
     ownQuestions: Arr(OwnQuestionSchema),
     questionsCursor: Schema.NullOr(Schema.String),
+    /** Admin-defined tag names, sorted. */
+    tags: Arr(Schema.String),
 });
 /** Body of `GET /api/pages/solo/layout`. */
 export const SoloLayoutPageSchema = Schema.Struct({
@@ -333,6 +390,7 @@ export const SoloLayoutPageSchema = Schema.Struct({
     nickname: Schema.String,
     profileAvatarSrc: Schema.String,
     categoryDataJson: Schema.String,
+    seasonDataJson: Schema.String,
 });
 const LeaderboardEntrySchema = Schema.Struct({
     rank: Schema.Number,
@@ -349,10 +407,19 @@ const LeaderboardEntrySchema = Schema.Struct({
 export const SoloLeaderboardPageSchema = Schema.Struct({
     entries: Arr(LeaderboardEntrySchema),
     board: Schema.Literal("score", "streak", "accuracy", "speed", "survival"),
-    scope: Schema.Literal("all-time", "daily", "weekly", "monthly"),
+    scope: Schema.Literal("all-time", "daily", "weekly", "monthly", "season"),
     categoryId: Schema.NullOr(Schema.String),
+    seasonId: Schema.NullOr(Schema.String),
+    opening: Schema.NullOr(Schema.String),
     difficulty: Schema.NullOr(Schema.Literal("easy", "medium", "hard")),
     categories: Arr(Schema.Struct({ id: Schema.String, name: Schema.String })),
+    seasonBoards: Arr(Schema.Struct({
+        seasonId: Schema.String,
+        name: Schema.String,
+        opening: Schema.String,
+        label: Schema.String,
+        current: Schema.Boolean,
+    })),
     userRank: Schema.NullOr(Schema.Number),
     eligibleCount: Schema.Number,
     percentile: Schema.NullOr(Schema.Number),

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

@@ -72,6 +72,7 @@ declare const SoloHistoryEntrySchema: Schema.Struct<{
     mode: typeof Schema.String;
     difficulty: typeof Schema.String;
     category_ids: typeof Schema.String;
+    seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
     completed_at: typeof Schema.Number;
 }>;
 export type SoloHistoryEntry = typeof SoloHistoryEntrySchema.Type;
@@ -89,6 +90,7 @@ declare const PlayerGamePlacementSchema: Schema.Struct<{
     final_score: typeof Schema.Number;
     rank: typeof Schema.Number;
     player_count: typeof Schema.Number;
+    seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
     badges: Schema.mutable<Schema.Array$<Schema.Literal<["victor", "flawless", "sharpshooter", "podium", "unstoppable", "on-a-roll", "survivor", "giant-slayer", "pantheon", "specialist", "polymath", "phoenix", "strong-finish", "master-of-none", "faster-than-most", "clutch", "quick-draw", "decisive", "sure-handed", "unbroken-focus", "devotee", "herculean", "undaunted", "measured", "strong-start", "new-heights", "far-horizons", "cassandra", "lone-torch", "ascendant", "undisputed"]>>>;
 }>;
 export type PlayerGamePlacement = typeof PlayerGamePlacementSchema.Type;
@@ -105,6 +107,7 @@ export declare const HistoryPageSchema: Schema.Struct<{
         mode: typeof Schema.String;
         difficulty: typeof Schema.String;
         category_ids: typeof Schema.String;
+        seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
         completed_at: typeof Schema.Number;
     }>>>;
     trendRuns: Schema.mutable<Schema.Array$<Schema.Struct<{
@@ -117,6 +120,7 @@ export declare const HistoryPageSchema: Schema.Struct<{
         mode: typeof Schema.String;
         difficulty: typeof Schema.String;
         category_ids: typeof Schema.String;
+        seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
         completed_at: typeof Schema.Number;
     }>>>;
     latestRunAt: Schema.NullOr<typeof Schema.Number>;
@@ -164,6 +168,7 @@ export declare const HistoryPageSchema: Schema.Struct<{
         final_score: typeof Schema.Number;
         rank: typeof Schema.Number;
         player_count: typeof Schema.Number;
+        seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
         badges: Schema.mutable<Schema.Array$<Schema.Literal<["victor", "flawless", "sharpshooter", "podium", "unstoppable", "on-a-roll", "survivor", "giant-slayer", "pantheon", "specialist", "polymath", "phoenix", "strong-finish", "master-of-none", "faster-than-most", "clutch", "quick-draw", "decisive", "sure-handed", "unbroken-focus", "devotee", "herculean", "undaunted", "measured", "strong-start", "new-heights", "far-horizons", "cassandra", "lone-torch", "ascendant", "undisputed"]>>>;
     }>>>;
     runsNextCursor: Schema.NullOr<typeof Schema.String>;
@@ -178,6 +183,7 @@ export declare const GameReviewPageSchema: Schema.Struct<{
         finalScore: typeof Schema.Number;
         rank: typeof Schema.Number;
         playerCount: typeof Schema.Number;
+        seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
     }>;
     standings: Schema.mutable<Schema.Array$<Schema.Struct<{
         id: typeof Schema.String;
@@ -238,6 +244,7 @@ export declare const SoloReviewPageSchema: Schema.Struct<{
         difficulty: typeof Schema.String;
         completedAt: typeof Schema.Number;
         categories: Schema.mutable<Schema.Array$<typeof Schema.String>>;
+        seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
     }>;
     badges: Schema.mutable<Schema.Array$<Schema.Struct<{
         id: Schema.Literal<["victor", "flawless", "sharpshooter", "podium", "unstoppable", "on-a-roll", "survivor", "giant-slayer", "pantheon", "specialist", "polymath", "phoenix", "strong-finish", "master-of-none", "faster-than-most", "clutch", "quick-draw", "decisive", "sure-handed", "unbroken-focus", "devotee", "herculean", "undaunted", "measured", "strong-start", "new-heights", "far-horizons", "cassandra", "lone-torch", "ascendant", "undisputed"]>;

package/dist/pages/history.schema.js

@@ -75,6 +75,7 @@ const SoloHistoryEntrySchema = Schema.Struct({
     mode: Schema.String,
     difficulty: Schema.String,
     category_ids: Schema.String,
+    seasons: Schema.mutable(Schema.Array(Schema.String)),
     completed_at: Schema.Number,
 });
 const SoloStatsSchema = Schema.Struct({
@@ -107,6 +108,7 @@ const PlayerGamePlacementSchema = Schema.Struct({
     final_score: Schema.Number,
     rank: Schema.Number,
     player_count: Schema.Number,
+    seasons: Schema.mutable(Schema.Array(Schema.String)),
     badges: Schema.mutable(Schema.Array(BadgeIdSchema)),
 });
 /** Body of `GET /api/pages/history`. */
@@ -150,6 +152,7 @@ export const GameReviewPageSchema = Schema.Struct({
         finalScore: Schema.Number,
         rank: Schema.Number,
         playerCount: Schema.Number,
+        seasons: Schema.mutable(Schema.Array(Schema.String)),
     }),
     standings: Schema.mutable(Schema.Array(GameStandingEntrySchema)),
     badges: Schema.mutable(Schema.Array(Schema.Struct({ id: BadgeIdSchema, rarity: RaritySchema }))),
@@ -193,6 +196,7 @@ export const SoloReviewPageSchema = Schema.Struct({
         difficulty: Schema.String,
         completedAt: Schema.Number,
         categories: Schema.mutable(Schema.Array(Schema.String)),
+        seasons: Schema.mutable(Schema.Array(Schema.String)),
     }),
     badges: Schema.mutable(Schema.Array(Schema.Struct({ id: BadgeIdSchema, rarity: RaritySchema }))),
     categoryStats: Schema.mutable(Schema.Array(Schema.Struct({

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

@@ -96,6 +96,7 @@ export declare const QuizContextPageSchema: Schema.Struct<{
         quizName: typeof Schema.String;
         description: typeof Schema.String;
         categories: Schema.mutable<Schema.Array$<typeof Schema.String>>;
+        seasons: Schema.mutable<Schema.Array$<typeof Schema.String>>;
         difficulty: Schema.NullOr<Schema.Literal<["all", "easy", "medium", "hard"]>>;
         accessMode: Schema.Literal<["open", "invite-only"]>;
         maxPlayers: Schema.NullOr<typeof Schema.Number>;

package/dist/pages/quiz.schema.js

@@ -85,6 +85,7 @@ const LobbySchema = Schema.Struct({
     quizName: Schema.String,
     description: Schema.String,
     categories: Schema.mutable(Schema.Array(Schema.String)),
+    seasons: Schema.mutable(Schema.Array(Schema.String)),
     difficulty: Schema.NullOr(DifficultyFilterSchema),
     accessMode: AccessModeSchema,
     maxPlayers: Schema.NullOr(Schema.Number),

package/dist/solo-ws.d.ts

@@ -10,6 +10,8 @@ export type SoloAuthMessage = {
 export type SoloStartMessage = {
     type: "solo:start";
     categoryIds: string[];
+    /** Seasons drawn from beside the categories. */
+    seasonIds?: string[];
     timerDuration: number;
     questionCount: number;
     mode: "normal" | "endless";
@@ -200,7 +202,7 @@ export type SoloPingMessage = {
 };
 export type SoloErrorMessage = {
     type: "solo:error";
-    code: "auth_failed" | "entitlement_exceeded" | "invalid_message" | "session_expired" | "internal";
+    code: "auth_failed" | "entitlement_exceeded" | "invalid_message" | "session_expired" | "season_out_of_season" | "no_questions" | "internal";
     message: string;
 };
 /** Build a `solo:error` frame — the one shape every failure site sends. */

package/dist/wire/leaderboard.d.ts

@@ -1,6 +1,6 @@
 /** Which ranking a leaderboard sorts by. */
 export type LeaderboardBoard = "score" | "streak" | "accuracy" | "speed" | "survival";
-/** Rolling window a leaderboard is scoped to. */
-export type LeaderboardScope = "all-time" | "daily" | "weekly" | "monthly";
+/** Rolling window a leaderboard is scoped to, or one Season opening. */
+export type LeaderboardScope = "all-time" | "daily" | "weekly" | "monthly" | "season";
 /** Difficulty filter a leaderboard is narrowed to. */
 export type LeaderboardDifficulty = "easy" | "medium" | "hard";

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

@@ -23,6 +23,7 @@ export declare const ClientMessageSchema: Schema.Union<[Schema.Struct<{
 }>, Schema.Struct<{
     type: Schema.Literal<["curator:start"]>;
     categoryIds: Schema.optional<Schema.filter<Schema.Array$<typeof Schema.NonEmptyString>>>;
+    seasonIds: Schema.optional<Schema.filter<Schema.Array$<typeof Schema.NonEmptyString>>>;
     timerDuration: Schema.optional<Schema.Literal<[15, 30, 45, 60]>>;
     questionsPerRound: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
     difficulty: Schema.optional<Schema.Literal<["all", "easy", "medium", "hard"]>>;

package/dist/ws-game.schema.js

@@ -94,6 +94,7 @@ const CuratorStartMessageSchema = Schema.Struct({
     // preloadedQuestions carries the round — game-ws-server.ts's makeStartGame
     // surfaces the friendly "select a category" error itself.
     categoryIds: Schema.optional(Schema.Array(Schema.NonEmptyString).pipe(Schema.maxItems(50))),
+    seasonIds: Schema.optional(Schema.Array(Schema.NonEmptyString).pipe(Schema.maxItems(50))),
     timerDuration: Schema.optional(Schema.Literal(...GAME.roundConfig.timerOptions)),
     // Not the QuestionsPerRound literal on purpose (ws.ts types this as a plain
     // number) — bounded generously instead, mirroring DrawQuestionsSchema's cap.

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

@@ -5,6 +5,7 @@ export declare const SoloClientMessageSchema: Schema.Union<[Schema.Struct<{
 }>, Schema.Struct<{
     type: Schema.Literal<["solo:start"]>;
     categoryIds: Schema.filter<Schema.Array$<typeof Schema.NonEmptyString>>;
+    seasonIds: Schema.optional<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"]>;

package/dist/ws-solo.schema.js

@@ -17,6 +17,7 @@ const SoloAuthMessageSchema = Schema.Struct({
 const SoloStartMessageSchema = Schema.Struct({
     type: Schema.Literal("solo:start"),
     categoryIds: Schema.Array(Schema.NonEmptyString).pipe(Schema.maxItems(50)),
+    seasonIds: Schema.optional(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)),

package/dist/ws.d.ts

@@ -49,6 +49,9 @@ export interface PlayerRateMessage {
 export interface CuratorStartMessage {
     type: "curator:start";
     categoryIds?: string[];
+    /** Season ids; the server keeps only those the Lobby fixed at create or
+     *  re-host. */
+    seasonIds?: string[];
     timerDuration?: TimerDuration;
     questionsPerRound?: number;
     difficulty?: DifficultyFilter;
@@ -108,6 +111,8 @@ export interface LobbyUpdateMessage {
     description?: string;
     /** Curator's live-edited category list. */
     categories?: readonly string[];
+    /** Names of the Seasons the Lobby draws from. */
+    seasons?: readonly string[];
     /** Curator's live-edited difficulty filter. */
     difficulty?: DifficultyFilter;
 }

package/package.json

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