@orakl/protocol 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export * from "./pages/common.schema.ts";
 export * from "./pages/history.schema.ts";
 export * from "./pages/quiz.schema.ts";
 export type { PlayerSafeQuestion } from "./player-safe-question.ts";
-export { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, type CreditLicence, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, type ImageChoiceQuestion, type ImageMatchingQuestion, isHttpsUrl, type Media, type MediaCredit, MediaCreditSchema, 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 { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, type CreditLicence, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, type ImageChoiceQuestion, type ImageMatchingQuestion, isHttpsUrl, type Media, type MediaCredit, MediaCreditSchema, MediaSchema, type MediaType, MediaTypeSchema, POST_ANSWER_NOTE_MAX_LEN, PostAnswerNoteSchema, type Question, QuestionSchema, type QuestionSource, QuestionSourceSchema, type QuestionType, QuestionTypeSchema, SOURCE_LABEL_MAX_LEN, SOURCE_URL_MAX_LEN, 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";

package/dist/index.js

@@ -5,7 +5,7 @@ export * from "./pages/auth.schema.js";
 export * from "./pages/common.schema.js";
 export * from "./pages/history.schema.js";
 export * from "./pages/quiz.schema.js";
-export { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, isHttpsUrl, MediaCreditSchema, MediaSchema, MediaTypeSchema, PostAnswerNoteSchema, QuestionSchema, QuestionSourceSchema, QuestionTypeSchema, SourceSchema, } from "./question.schema.js";
+export { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, isHttpsUrl, MediaCreditSchema, MediaSchema, MediaTypeSchema, POST_ANSWER_NOTE_MAX_LEN, PostAnswerNoteSchema, QuestionSchema, QuestionSourceSchema, QuestionTypeSchema, SOURCE_LABEL_MAX_LEN, SOURCE_URL_MAX_LEN, SourceSchema, } from "./question.schema.js";
 export { hasMedia, isImageMatching, isTextChoice, isTrueFalse, } from "./question.js";
 export { OptionalScoringModeSchema, ScoringModeSchema, } from "./scoring.schema.js";
 export { soloError, } from "./solo-ws.js";

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

@@ -288,6 +288,47 @@ export declare const ManageQuestionRatingsPageSchema: Schema.Struct<{
     initialHasMore: typeof Schema.Boolean;
     page: typeof Schema.Number;
 }>;
+declare const BankQuestionRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    excerpt: typeof Schema.String;
+    source: Schema.Literal<["built-in", "promoted"]>;
+    category: typeof Schema.String;
+    /** The stored question type, e.g. `text_choice`. */
+    type: typeof Schema.String;
+    difficulty: Schema.NullOr<Schema.Literal<["easy", "medium", "hard"]>>;
+    /** At least one revision exists. */
+    edited: typeof Schema.Boolean;
+}>;
+/** One question an operator may edit on the question bank page: built-in or promoted. */
+export type BankQuestionRow = typeof BankQuestionRowSchema.Type;
+/** Body of `GET /api/pages/manage/bank`. */
+export declare const ManageBankPageSchema: Schema.Struct<{
+    initial: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly type: string;
+        readonly source: "built-in" | "promoted";
+        readonly id: string;
+        readonly category: string;
+        readonly difficulty: "medium" | "easy" | "hard" | null;
+        readonly excerpt: string;
+        readonly edited: boolean;
+    }, {
+        readonly type: string;
+        readonly source: "built-in" | "promoted";
+        readonly id: string;
+        readonly category: string;
+        readonly difficulty: "medium" | "easy" | "hard" | null;
+        readonly excerpt: string;
+        readonly edited: boolean;
+    }, never>>>;
+    initialHasMore: typeof Schema.Boolean;
+    page: typeof Schema.Number;
+    /** The search term the page was loaded with; empty for none. */
+    q: typeof Schema.String;
+    /** The category name the page was filtered to; empty for all. */
+    category: typeof Schema.String;
+    /** Category names offered by the filter, A to Z. */
+    categories: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+}>;
 declare const AuthoredQuestionRowSchema: Schema.Struct<{
     id: typeof Schema.String;
     category: typeof Schema.String;
@@ -623,12 +664,7 @@ export declare const CuratorHistoryEntryPageSchema: Schema.Struct<{
             readonly questionText?: string | undefined;
             readonly mediaUrl?: string | undefined;
             readonly mediaType?: "audio" | "video" | "image" | undefined;
-            readonly mediaCredit?: {
-                readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
-                readonly author?: string | undefined;
-                readonly sourceUrl?: string | undefined;
-                readonly licenceUrl?: string | undefined;
-            } | undefined;
+            readonly mediaCredit?: unknown;
         }, never>>>>;
     }>;
     presetLimit: typeof Schema.Number;

package/dist/pages/app.schema.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import { EmoteSetSchema } from "../emotes.js";
-import { MediaCreditSchema, MediaTypeSchema, StoredQuestionSourceSchema, } from "../question.schema.js";
+import { MediaTypeSchema, StoredMediaCreditSchema, StoredQuestionSourceSchema, } from "../question.schema.js";
 import { ThemeModeSchema, UserPowerSchema, UserRoleSchema, } from "./common.schema.js";
 /** Page-load response bodies for `src/api/routes/pages.ts`. */
 /** A JSON array, decoded mutable — Effect's `Schema.Array` types its `.Type`
@@ -196,6 +196,29 @@ export const ManageQuestionRatingsPageSchema = Schema.Struct({
     initialHasMore: Schema.Boolean,
     page: Schema.Number,
 });
+const BankQuestionRowSchema = Schema.Struct({
+    id: Schema.String,
+    excerpt: Schema.String,
+    source: Schema.Literal("built-in", "promoted"),
+    category: Schema.String,
+    /** The stored question type, e.g. `text_choice`. */
+    type: Schema.String,
+    difficulty: Schema.NullOr(Schema.Literal("easy", "medium", "hard")),
+    /** At least one revision exists. */
+    edited: Schema.Boolean,
+});
+/** Body of `GET /api/pages/manage/bank`. */
+export const ManageBankPageSchema = Schema.Struct({
+    initial: Arr(BankQuestionRowSchema),
+    initialHasMore: Schema.Boolean,
+    page: Schema.Number,
+    /** The search term the page was loaded with; empty for none. */
+    q: Schema.String,
+    /** The category name the page was filtered to; empty for all. */
+    category: Schema.String,
+    /** Category names offered by the filter, A to Z. */
+    categories: Arr(Schema.String),
+});
 const AuthoredQuestionRowSchema = Schema.Struct({
     id: Schema.String,
     category: Schema.String,
@@ -341,7 +364,7 @@ const QuestionRecapEntrySchema = Schema.Struct({
     questionText: Schema.optional(Schema.String),
     mediaUrl: Schema.optional(Schema.String),
     mediaType: Schema.optional(MediaTypeSchema),
-    mediaCredit: Schema.optional(MediaCreditSchema),
+    mediaCredit: Schema.optional(StoredMediaCreditSchema),
     source: Schema.optional(StoredQuestionSourceSchema),
     postAnswerNote: Schema.optional(Schema.String),
     answered: Schema.Number,

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

@@ -19,12 +19,17 @@ export declare const GameAnswerRecordSchema: Schema.Struct<{
     correctAnswerText: Schema.optional<typeof Schema.String>;
     mediaUrl: Schema.optional<typeof Schema.String>;
     mediaType: Schema.optional<Schema.Literal<["image", "audio", "video"]>>;
-    mediaCredit: Schema.optional<Schema.filter<Schema.Struct<{
-        licence: Schema.Literal<["cc0", "public-domain", "cc-by", "cc-by-sa", "own"]>;
-        author: Schema.optional<Schema.filter<typeof Schema.String>>;
-        sourceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-        licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-    }>>>;
+    mediaCredit: Schema.optional<Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
+        readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+        readonly author?: string | undefined;
+        readonly sourceUrl?: string | undefined;
+        readonly licenceUrl?: string | undefined;
+    }, {
+        readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+        readonly author?: string | undefined;
+        readonly sourceUrl?: string | undefined;
+        readonly licenceUrl?: string | undefined;
+    }, never>>>>;
     source: Schema.optional<Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
         readonly url: string;
         readonly label?: string | undefined;

package/dist/pages/common.schema.js

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import { MediaCreditSchema, MediaTypeSchema, StoredQuestionSourceSchema, } from "../question.schema.js";
+import { MediaTypeSchema, StoredMediaCreditSchema, StoredQuestionSourceSchema, } from "../question.schema.js";
 /** Schemas shared by more than one page-load body. */
 export const UserRoleSchema = Schema.Literal("anonymous", "display", "member", "curator", "admin");
 export const UserPowerSchema = Schema.Literal("can-access-mimic", "can-send-feedback", "can-import-quizzes", "can-manage-features", "can-add-questions", "can-manage-categories", "can-moderate-questions", "can-publish-questions", "is-power-user", "can-manage-avatars", "can-apply-for-curation", "can-1v1");
@@ -20,7 +20,7 @@ export const GameAnswerRecordSchema = Schema.Struct({
     correctAnswerText: Schema.optional(Schema.String),
     mediaUrl: Schema.optional(Schema.String),
     mediaType: Schema.optional(MediaTypeSchema),
-    mediaCredit: Schema.optional(MediaCreditSchema),
+    mediaCredit: Schema.optional(StoredMediaCreditSchema),
     source: Schema.optional(StoredQuestionSourceSchema),
     postAnswerNote: Schema.optional(Schema.String),
 });

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

@@ -241,12 +241,17 @@ export declare const GameReviewPageSchema: Schema.Struct<{
         correctAnswerText: Schema.optional<typeof Schema.String>;
         mediaUrl: Schema.optional<typeof Schema.String>;
         mediaType: Schema.optional<Schema.Literal<["image", "audio", "video"]>>;
-        mediaCredit: Schema.optional<Schema.filter<Schema.Struct<{
-            licence: Schema.Literal<["cc0", "public-domain", "cc-by", "cc-by-sa", "own"]>;
-            author: Schema.optional<Schema.filter<typeof Schema.String>>;
-            sourceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-            licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-        }>>>;
+        mediaCredit: Schema.optional<Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
+            readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+            readonly author?: string | undefined;
+            readonly sourceUrl?: string | undefined;
+            readonly licenceUrl?: string | undefined;
+        }, {
+            readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+            readonly author?: string | undefined;
+            readonly sourceUrl?: string | undefined;
+            readonly licenceUrl?: string | undefined;
+        }, never>>>>;
         source: Schema.optional<Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
             readonly url: string;
             readonly label?: string | undefined;
@@ -302,12 +307,17 @@ export declare const SoloReviewPageSchema: Schema.Struct<{
         questionId: Schema.NullOr<typeof Schema.String>;
         mediaUrl: Schema.NullOr<typeof Schema.String>;
         mediaType: Schema.NullOr<Schema.Literal<["image", "audio", "video"]>>;
-        mediaCredit: Schema.optional<Schema.NullOr<Schema.filter<Schema.Struct<{
-            licence: Schema.Literal<["cc0", "public-domain", "cc-by", "cc-by-sa", "own"]>;
-            author: Schema.optional<Schema.filter<typeof Schema.String>>;
-            sourceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-            licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-        }>>>>;
+        mediaCredit: Schema.optional<Schema.Union<[typeof Schema.Null, Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
+            readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+            readonly author?: string | undefined;
+            readonly sourceUrl?: string | undefined;
+            readonly licenceUrl?: string | undefined;
+        }, {
+            readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+            readonly author?: string | undefined;
+            readonly sourceUrl?: string | undefined;
+            readonly licenceUrl?: string | undefined;
+        }, never>>>]>>;
         source: Schema.Union<[typeof Schema.Null, Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
             readonly url: string;
             readonly label?: string | undefined;

package/dist/pages/history.schema.js

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import { MediaCreditSchema, MediaTypeSchema, StoredQuestionSourceSchema, } from "../question.schema.js";
+import { MediaTypeSchema, StoredMediaCreditSchema, StoredQuestionSourceSchema, } from "../question.schema.js";
 import { GameAnswerRecordSchema, PlayerRoleSchema, UserPowerSchema, UserRoleSchema, } from "./common.schema.js";
 /** Page-load response bodies for `src/api/routes/pages-history.ts and admin-feature-flags.ts`. */
 /** Achievement badge id (mirrors `BadgeId` in `src/lib/badges.ts`). */
@@ -208,7 +208,8 @@ const SoloRunReviewEntrySchema = Schema.Struct({
     mediaUrl: Schema.NullOr(Schema.String),
     mediaType: Schema.NullOr(MediaTypeSchema),
     // Optional: a review served before credits existed has no key.
-    mediaCredit: Schema.optional(Schema.NullOr(MediaCreditSchema)),
+    // Null first: the stored-credit transform accepts any value, null included.
+    mediaCredit: Schema.optional(Schema.Union(Schema.Null, StoredMediaCreditSchema)),
     // Null first: the stored-source transform accepts any value, null included.
     source: Schema.Union(Schema.Null, StoredQuestionSourceSchema),
     postAnswerNote: Schema.NullOr(Schema.String),

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

@@ -152,12 +152,17 @@ export declare const QuizResultsPageSchema: Schema.Struct<{
         correctAnswerText: Schema.optional<typeof Schema.String>;
         mediaUrl: Schema.optional<typeof Schema.String>;
         mediaType: Schema.optional<Schema.Literal<["image", "audio", "video"]>>;
-        mediaCredit: Schema.optional<Schema.filter<Schema.Struct<{
-            licence: Schema.Literal<["cc0", "public-domain", "cc-by", "cc-by-sa", "own"]>;
-            author: Schema.optional<Schema.filter<typeof Schema.String>>;
-            sourceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-            licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
-        }>>>;
+        mediaCredit: Schema.optional<Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
+            readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+            readonly author?: string | undefined;
+            readonly sourceUrl?: string | undefined;
+            readonly licenceUrl?: string | undefined;
+        }, {
+            readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+            readonly author?: string | undefined;
+            readonly sourceUrl?: string | undefined;
+            readonly licenceUrl?: string | undefined;
+        }, never>>>>;
         source: Schema.optional<Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
             readonly url: string;
             readonly label?: string | undefined;

package/dist/question.schema.d.ts

@@ -24,6 +24,22 @@ export declare const MediaCreditSchema: Schema.filter<Schema.Struct<{
     licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
 }>>;
 export type MediaCredit = typeof MediaCreditSchema.Type;
+/**
+ * Read-side credit: a stored value that fails `MediaCreditSchema` (a rule
+ * tightened after it was written, a wrong shape) decodes to undefined, so one
+ * bad credit never fails a whole page.
+ */
+export declare const StoredMediaCreditSchema: Schema.transform<typeof Schema.Unknown, Schema.UndefinedOr<Schema.SchemaClass<{
+    readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+    readonly author?: string | undefined;
+    readonly sourceUrl?: string | undefined;
+    readonly licenceUrl?: string | undefined;
+}, {
+    readonly licence: "cc0" | "public-domain" | "cc-by" | "cc-by-sa" | "own";
+    readonly author?: string | undefined;
+    readonly sourceUrl?: string | undefined;
+    readonly licenceUrl?: string | undefined;
+}, never>>>;
 export declare const MediaSchema: Schema.Struct<{
     type: Schema.Literal<["image", "audio", "video"]>;
     url: typeof Schema.String;
@@ -37,6 +53,12 @@ export declare const MediaSchema: Schema.Struct<{
         licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
     }>>>;
 }>;
+/** Max characters in a question source URL. */
+export declare const SOURCE_URL_MAX_LEN = 2048;
+/** Max characters in a question source label. */
+export declare const SOURCE_LABEL_MAX_LEN = 200;
+/** Max characters in a post-answer note. */
+export declare const POST_ANSWER_NOTE_MAX_LEN = 160;
 export declare const QuestionSourceSchema: Schema.Struct<{
     url: Schema.filter<Schema.filter<typeof Schema.String>>;
     label: Schema.optional<Schema.filter<typeof Schema.String>>;

package/dist/question.schema.js

@@ -57,6 +57,17 @@ export const MediaCreditSchema = Schema.Struct({
 }).pipe(Schema.filter((c) => !ATTRIBUTION_LICENCES.includes(c.licence) ||
     Boolean(c.author?.trim()) ||
     "Author is required for CC BY and CC BY-SA"));
+const isMediaCredit = Schema.is(MediaCreditSchema);
+/**
+ * Read-side credit: a stored value that fails `MediaCreditSchema` (a rule
+ * tightened after it was written, a wrong shape) decodes to undefined, so one
+ * bad credit never fails a whole page.
+ */
+export const StoredMediaCreditSchema = Schema.transform(Schema.Unknown, Schema.UndefinedOr(Schema.typeSchema(MediaCreditSchema)), {
+    strict: true,
+    decode: (credit) => (isMediaCredit(credit) ? credit : undefined),
+    encode: (credit) => credit,
+});
 export const MediaSchema = Schema.Struct({
     type: MediaTypeSchema,
     url: Schema.String,
@@ -66,13 +77,19 @@ export const MediaSchema = Schema.Struct({
 // Security: source.url is stored in the DB and read back on results/history
 // pages; cap to match imageUrl's bound (curator.schema.ts) since both are
 // URLs of the same practical size.
-const HttpsUrlSchema = Schema.String.pipe(Schema.maxLength(2048, {
-    message: () => "Source URL must be 2048 characters or fewer",
+/** Max characters in a question source URL. */
+export const SOURCE_URL_MAX_LEN = 2048;
+/** Max characters in a question source label. */
+export const SOURCE_LABEL_MAX_LEN = 200;
+/** Max characters in a post-answer note. */
+export const POST_ANSWER_NOTE_MAX_LEN = 160;
+const HttpsUrlSchema = Schema.String.pipe(Schema.maxLength(SOURCE_URL_MAX_LEN, {
+    message: () => `Source URL must be ${SOURCE_URL_MAX_LEN} characters or fewer`,
 }), Schema.filter(isHttpsUrl, { message: () => "Source URL must be https" }));
 export const QuestionSourceSchema = Schema.Struct({
     url: HttpsUrlSchema,
-    label: Schema.optional(Schema.String.pipe(Schema.maxLength(200, {
-        message: () => "Source label must be 200 characters or fewer",
+    label: Schema.optional(Schema.String.pipe(Schema.maxLength(SOURCE_LABEL_MAX_LEN, {
+        message: () => `Source label must be ${SOURCE_LABEL_MAX_LEN} characters or fewer`,
     }))),
 });
 const isQuestionSource = Schema.is(QuestionSourceSchema);
@@ -86,8 +103,8 @@ export const StoredQuestionSourceSchema = Schema.transform(Schema.Unknown, Schem
     decode: (source) => (isQuestionSource(source) ? source : undefined),
     encode: (source) => source,
 });
-export const PostAnswerNoteSchema = Schema.String.pipe(Schema.maxLength(160, {
-    message: () => "Post-answer note must be 160 characters or fewer",
+export const PostAnswerNoteSchema = Schema.String.pipe(Schema.maxLength(POST_ANSWER_NOTE_MAX_LEN, {
+    message: () => `Post-answer note must be ${POST_ANSWER_NOTE_MAX_LEN} characters or fewer`,
 }));
 const MetadataSchema = Schema.Struct({
     source: SourceSchema,

package/package.json

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