@read-frog/api-contract 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.19.0",
+  "version": "0.20.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.9.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/index.ts

@@ -5,6 +5,7 @@ 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";
@@ -21,6 +22,7 @@ export const contract = {
   cardTemplate: cardTemplateContract,
   ebook: ebookContract,
   hostedAi: hostedAiContract,
+  masteryGoal: masteryGoalContract,
   mcpConnection: mcpConnectionContract,
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
@@ -40,6 +42,7 @@ 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";

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,
 });
@@ -148,7 +175,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/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>;