@read-frog/api-contract 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@orpc/contract": "^1.15.2",
-    "@read-frog/definitions": "0.8.0",
+    "@read-frog/definitions": "0.10.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/contracts/card-template.ts

@@ -42,10 +42,16 @@ export const cardTemplateContract = {
     path: "/card-templates",
     summary: "Create card template",
     description:
-      "Create a template in an owned notebase using existing field IDs in its patterns. This generates cards for existing notes.",
+      'Create a template in an owned notebase; it generates a card for every existing note. Each face (front, back) is either { columns: [column IDs], style }, those columns in a built-in style that stays editable in the website\'s simple mode, or { layout: "<HTML + Liquid>" } for a custom design that references a column as {{ ["<column id>"] }}. Prefer columns faces. Get column IDs from the notebase schema.',
     tags: ["Card Templates"],
   })
-    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS"))
+    .errors(
+      pickPublicErrorMap(
+        "NOTEBASE_NOT_FOUND",
+        "CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS",
+        "CARD_TEMPLATE_INVALID_LAYOUT",
+      ),
+    )
     .errors(pickPublicErrorMap("RESOURCE_ALREADY_EXISTS"))
     .input(CardTemplateCreateInputSchema)
     .output(CardTemplateCreateOutputSchema),
@@ -55,10 +61,16 @@ export const cardTemplateContract = {
     path: "/card-templates/{id}",
     summary: "Update card template",
     description:
-      "Change an owned template name or definition. Rendered cards reflect the saved template. expectedUpdatedAt guards against editing stale data.",
+      "Change an owned template name or faces (see creating a template for the face shapes). Rendered cards reflect the saved template. expectedUpdatedAt guards against editing stale data.",
     tags: ["Card Templates"],
   })
-    .errors(pickPublicErrorMap("CARD_TEMPLATE_NOT_FOUND", "CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS"))
+    .errors(
+      pickPublicErrorMap(
+        "CARD_TEMPLATE_NOT_FOUND",
+        "CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS",
+        "CARD_TEMPLATE_INVALID_LAYOUT",
+      ),
+    )
     .errors(pickPublicErrorMap("RESOURCE_UPDATE_CONFLICT"))
     .input(CardTemplateUpdateInputSchema)
     .output(CardTemplateUpdateOutputSchema),

package/src/contracts/mastery-goal.ts

@@ -0,0 +1,22 @@
+import { oc } from "@orpc/contract";
+import { masteryGoalOutputSchema, masteryGoalUpdateInputSchema } from "#/schemas/mastery-goal";
+
+export const masteryGoalContract = {
+  get: oc
+    .route({
+      method: "GET",
+      path: "/mastery-goal",
+      summary: "Get the authenticated user's mastered-cards goal",
+      tags: ["Goals"],
+    })
+    .output(masteryGoalOutputSchema),
+  update: oc
+    .route({
+      method: "PUT",
+      path: "/mastery-goal",
+      summary: "Set or clear the authenticated user's mastered-cards goal",
+      tags: ["Goals"],
+    })
+    .input(masteryGoalUpdateInputSchema)
+    .output(masteryGoalOutputSchema),
+};

package/src/contracts/speech.ts

@@ -0,0 +1,45 @@
+import { oc } from "@orpc/contract";
+import {
+  speechPreferencesSchema,
+  speechPreferencesUpdateInputSchema,
+  speechSynthesizeInputSchema,
+  speechSynthesizeOutputSchema,
+  speechVoicesOutputSchema,
+} from "#/schemas/speech";
+
+export const speechContract = {
+  getPreferences: oc
+    .route({
+      method: "GET",
+      path: "/speech/preferences",
+      summary: "Get how the authenticated user's text is read aloud",
+      tags: ["Speech"],
+    })
+    .output(speechPreferencesSchema),
+  updatePreferences: oc
+    .route({
+      method: "PATCH",
+      path: "/speech/preferences",
+      summary: "Change how the authenticated user's text is read aloud",
+      tags: ["Speech"],
+    })
+    .input(speechPreferencesUpdateInputSchema)
+    .output(speechPreferencesSchema),
+  listVoices: oc
+    .route({
+      method: "GET",
+      path: "/speech/voices",
+      summary: "List the voices text can be read aloud in, and each language's default",
+      tags: ["Speech"],
+    })
+    .output(speechVoicesOutputSchema),
+  synthesize: oc
+    .route({
+      method: "POST",
+      path: "/speech/synthesize",
+      summary: "Read a text aloud, as MP3 audio",
+      tags: ["Speech"],
+    })
+    .input(speechSynthesizeInputSchema)
+    .output(speechSynthesizeOutputSchema),
+};

package/src/index.ts

@@ -5,10 +5,12 @@ import { cardContract } from "./contracts/card";
 import { cardTemplateContract } from "./contracts/card-template";
 import { ebookContract } from "./contracts/ebook";
 import { hostedAiContract } from "./contracts/hosted-ai";
+import { masteryGoalContract } from "./contracts/mastery-goal";
 import { mcpConnectionContract } from "./contracts/mcp-connection";
 import { notebaseContract } from "./contracts/notebase";
 import { notebaseColumnContract } from "./contracts/notebase-column";
 import { notebaseRowContract } from "./contracts/notebase-row";
+import { speechContract } from "./contracts/speech";
 import { srsContract } from "./contracts/srs";
 import { statsContract } from "./contracts/stats";
 import { userContract } from "./contracts/user";
@@ -21,10 +23,12 @@ export const contract = {
   cardTemplate: cardTemplateContract,
   ebook: ebookContract,
   hostedAi: hostedAiContract,
+  masteryGoal: masteryGoalContract,
   mcpConnection: mcpConnectionContract,
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
+  speech: speechContract,
   srs: srsContract,
   stats: statsContract,
   user: userContract,
@@ -40,12 +44,14 @@ export * from "./schemas/billing";
 export * from "./schemas/card";
 export * from "./schemas/ebook";
 export * from "./schemas/hosted-ai";
+export * from "./schemas/mastery-goal";
 export * from "./schemas/mcp-connection";
 export * from "./schemas/notebase";
 export * from "./schemas/notebase-column";
 export * from "./schemas/notebase-row";
 export * from "./schemas/notebase-stats";
 export * from "./schemas/notebase-view";
+export * from "./schemas/speech";
 export * from "./schemas/srs";
 export * from "./schemas/srs-stats";
 export * from "./schemas/stats";

package/src/public-errors.ts

@@ -45,6 +45,33 @@ export const CardTemplateInvalidColumnsDataSchema = z
   .strict();
 export type CardTemplateInvalidColumnsData = z.infer<typeof CardTemplateInvalidColumnsDataSchema>;
 
+export const CardTemplateInvalidLayoutDataSchema = z
+  .object({
+    errors: z.array(
+      z
+        .object({
+          side: z.enum(["front", "back"]),
+          message: z.string(),
+          // UTF-16 offsets into that face's layout, when the parser knows them.
+          from: z.number().int().min(0).optional(),
+          to: z.number().int().min(0).optional(),
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+export type CardTemplateInvalidLayoutData = z.infer<typeof CardTemplateInvalidLayoutDataSchema>;
+
+// The templates that use the column, which keep it from being deleted.
+export const CardTemplateNotebaseColumnInUseDataSchema = z
+  .object({
+    templates: z.array(z.object({ id: z.uuid(), name: z.string() }).strict()),
+  })
+  .strict();
+export type CardTemplateNotebaseColumnInUseData = z.infer<
+  typeof CardTemplateNotebaseColumnInUseDataSchema
+>;
+
 export const HostedAiTierRestrictedDataSchema = z.strictObject({
   modelTier: HostedAiModelTierSchema,
 });
@@ -60,6 +87,11 @@ export const HostedAiQuotaExhaustedDataSchema = z.strictObject({
   resetAt: z.iso.datetime().nullable(),
 });
 
+export const SpeechDailyLimitReachedDataSchema = z.strictObject({
+  limit: z.number().int().min(0),
+  resetAt: z.iso.datetime(),
+});
+
 export const PUBLIC_APP_ERROR_DEFS = {
   RESOURCE_UPDATE_CONFLICT: {
     message: "The resource changed. Read it again before updating.",
@@ -127,6 +159,17 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "This video is longer than AI subtitles support",
     status: 422,
   },
+  // The day's read-aloud requests are used up (`SPEECH_DAILY_REQUEST_LIMITS`).
+  SPEECH_DAILY_LIMIT_REACHED: {
+    data: SpeechDailyLimitReachedDataSchema,
+    message: "Today's read-aloud limit is reached",
+    status: 429,
+  },
+  // No voice service to read with right now: not configured, or failing.
+  SPEECH_UNAVAILABLE: {
+    message: "Reading aloud is unavailable right now",
+    status: 503,
+  },
   NOTEBASE_COLUMN_NOT_FOUND: {
     message: "Notebase column not found",
     status: 404,
@@ -148,7 +191,13 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Card template references unknown notebase columns",
     status: 422,
   },
+  CARD_TEMPLATE_INVALID_LAYOUT: {
+    data: CardTemplateInvalidLayoutDataSchema,
+    message: "Card template layout does not parse",
+    status: 422,
+  },
   CARD_TEMPLATE_NOTEBASE_COLUMN_IN_USE: {
+    data: CardTemplateNotebaseColumnInUseDataSchema,
     message: "Notebase column is used by a card template",
     status: 409,
   },

package/src/schemas/card.ts

@@ -5,6 +5,7 @@ import {
   cardMemoryStateShape,
   cardStateSchema,
   cardTemplateConfigSchema,
+  cardTemplateCreatedBySchema,
   scheduleStatusSchema,
 } from "@read-frog/definitions";
 import { z } from "zod";
@@ -17,6 +18,9 @@ export const cardTemplateSchema = z.object({
   notebaseId: z.uuid(),
   name: z.string(),
   config: cardTemplateConfigSchema,
+  createdBy: cardTemplateCreatedBySchema.describe(
+    'Who made the template: "user", or "system" for the default template Read Frog gives a notebase whose fields fit one.',
+  ),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 });

package/src/schemas/mastery-goal.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export const MASTERY_GOAL_TARGET_MAX = 1_000_000;
+
+/** How many mastered cards to aim for: the cards `stats.srsMemoryGrowth` counts. */
+export const masteryGoalTargetSchema = z.number().int().min(1).max(MASTERY_GOAL_TARGET_MAX);
+export type MasteryGoalTarget = z.infer<typeof masteryGoalTargetSchema>;
+
+/** `null` clears the goal. */
+export const masteryGoalUpdateInputSchema = z
+  .object({
+    target: masteryGoalTargetSchema.nullable(),
+  })
+  .strict();
+export type MasteryGoalUpdateInput = z.infer<typeof masteryGoalUpdateInputSchema>;
+
+/** The goal's target, or `null` while none is set. */
+export const masteryGoalOutputSchema = z
+  .object({
+    target: masteryGoalTargetSchema.nullable(),
+  })
+  .strict();
+export type MasteryGoalOutput = z.infer<typeof masteryGoalOutputSchema>;

package/src/schemas/speech.ts

@@ -0,0 +1,113 @@
+import type { BillingPlan } from "./billing";
+import { langCodeISO6393Schema } from "@read-frog/definitions";
+import { z } from "zod";
+
+// Reading text aloud in the account's voices: the reader's settings, the
+// voices to choose from, and the request that turns a text into audio.
+
+/** The longest text one request reads aloud. */
+export const SPEECH_TEXT_MAX_LENGTH = 500;
+
+/**
+ * How many texts each plan may have read aloud in a day (24 hours from the
+ * first one). Generous enough that reviewing never runs into it; the cap is
+ * there to keep the voices from being used as a free speech service.
+ */
+export const SPEECH_DAILY_REQUEST_LIMITS = {
+  free: 200,
+  pro: 5000,
+  ultra: 5000,
+} as const satisfies Record<BillingPlan, number>;
+
+/** A voice by its short name: its locale, then the voice (`en-US-AndrewMultilingualNeural`). */
+export const speechVoiceNameSchema = z
+  .string()
+  .max(100)
+  .regex(/^[a-z]{2,3}(?:-[A-Za-z0-9]+)+(?::[A-Za-z0-9]+)?$/);
+export type SpeechVoiceName = z.infer<typeof speechVoiceNameSchema>;
+
+export const SPEECH_RATE_MIN = -50;
+export const SPEECH_RATE_MAX = 100;
+
+/** Reading speed: percent faster (+) or slower (−) than normal. */
+export const speechRateSchema = z.number().int().min(SPEECH_RATE_MIN).max(SPEECH_RATE_MAX);
+
+/**
+ * How the account reads aloud. A language left out of `languageVoices`, and a
+ * `null` `multilingualVoice`, read in the default voice (`speech.listVoices`
+ * names them).
+ */
+export const speechPreferencesSchema = z
+  .object({
+    languageVoices: z.partialRecord(langCodeISO6393Schema, speechVoiceNameSchema),
+    // Reads text whose language is not known, working the language out itself.
+    multilingualVoice: speechVoiceNameSchema.nullable(),
+    rate: speechRateSchema,
+  })
+  .strict();
+export type SpeechPreferences = z.infer<typeof speechPreferencesSchema>;
+
+export const DEFAULT_SPEECH_PREFERENCES: SpeechPreferences = {
+  languageVoices: {},
+  multilingualVoice: null,
+  rate: 0,
+};
+
+/**
+ * Changes some settings and keeps the rest. `languageVoices` changes only the
+ * languages it names; `null` puts a language back on its default voice.
+ */
+export const speechPreferencesUpdateInputSchema = z
+  .object({
+    languageVoices: z
+      .partialRecord(langCodeISO6393Schema, speechVoiceNameSchema.nullable())
+      .optional(),
+    multilingualVoice: speechVoiceNameSchema.nullable().optional(),
+    rate: speechRateSchema.optional(),
+  })
+  .strict();
+export type SpeechPreferencesUpdateInput = z.infer<typeof speechPreferencesUpdateInputSchema>;
+
+export const speechVoiceGenderSchema = z.enum(["female", "male", "neutral"]);
+export type SpeechVoiceGender = z.infer<typeof speechVoiceGenderSchema>;
+
+export const speechVoiceSchema = z
+  .object({
+    name: speechVoiceNameSchema,
+    // The voice's name for people, such as "Andrew Multilingual".
+    displayName: z.string(),
+    locale: z.string(),
+    // The language the voice is for; null for one this list has no code for.
+    language: langCodeISO6393Schema.nullable(),
+    gender: speechVoiceGenderSchema,
+    // Reads many languages, working out the text's language itself.
+    multilingual: z.boolean(),
+  })
+  .strict();
+export type SpeechVoice = z.infer<typeof speechVoiceSchema>;
+
+export const speechVoicesOutputSchema = z
+  .object({
+    voices: z.array(speechVoiceSchema),
+    // The voice each language reads in until the reader picks one.
+    defaultVoices: z.partialRecord(langCodeISO6393Schema, speechVoiceNameSchema),
+    defaultMultilingualVoice: speechVoiceNameSchema,
+  })
+  .strict();
+export type SpeechVoicesOutput = z.infer<typeof speechVoicesOutputSchema>;
+
+export const speechSynthesizeInputSchema = z
+  .object({
+    text: z.string().trim().min(1).max(SPEECH_TEXT_MAX_LENGTH),
+    // The text's language, when the caller knows it; without one, a
+    // multilingual voice works it out.
+    language: langCodeISO6393Schema.optional(),
+    // Reads in this voice instead of the account's, such as one the reader is
+    // trying out in the settings.
+    voice: speechVoiceNameSchema.optional(),
+  })
+  .strict();
+export type SpeechSynthesizeInput = z.infer<typeof speechSynthesizeInputSchema>;
+
+/** The audio, as an MP3 file. */
+export const speechSynthesizeOutputSchema = z.file();