@read-frog/api-contract 0.20.0 → 0.21.0

package/package.json

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

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

@@ -10,6 +10,7 @@ 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";
@@ -27,6 +28,7 @@ export const contract = {
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
+  speech: speechContract,
   srs: srsContract,
   stats: statsContract,
   user: userContract,
@@ -49,6 +51,7 @@ 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

@@ -87,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.",
@@ -154,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,

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/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();