@read-frog/api-contract 0.18.1 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@orpc/contract": "^1.15.2",
-    "@read-frog/definitions": "0.7.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/contracts/srs.ts

@@ -8,6 +8,8 @@ import {
   srsListCardRevlogsOutputSchema,
   srsListUnreadOptimizerResultsInputSchema,
   srsListUnreadOptimizerResultsOutputSchema,
+  srsRecentNotebaseScheduleStatusStatsInputSchema,
+  srsRecentNotebaseScheduleStatusStatsOutputSchema,
   srsReviewInputSchema,
   srsReviewOutputSchema,
   srsRollbackReviewInputSchema,
@@ -32,6 +34,17 @@ export const srsContract = {
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
     .input(srsScheduleStatusStatsInputSchema)
     .output(srsScheduleStatusStatsOutputSchema),
+  recentNotebaseScheduleStatusStats: oc
+    .route({
+      method: "GET",
+      path: "/srs/schedule-status-stats/recent",
+      summary: "Get study queue counts of the most recently used notebase",
+      description:
+        "Picks the owned notebase with the latest review or content edit (notes, fields or templates) and returns its study queue counts in the supplied timezone.",
+      tags: ["SRS"],
+    })
+    .input(srsRecentNotebaseScheduleStatusStatsInputSchema)
+    .output(srsRecentNotebaseScheduleStatusStatsOutputSchema),
   listUnreadOptimizerResults: oc
     .route({
       method: "GET",

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>;

package/src/schemas/notebase.ts

@@ -2,6 +2,7 @@ import { deletionResultSchema } from "./resource-mutation";
 import {
   notebaseColumnConfigSchema,
   schedulingParamsShape,
+  srsModelVersionSchema,
   srsWeightsSchema,
 } from "@read-frog/definitions";
 import { z } from "zod";
@@ -38,6 +39,8 @@ export const notebaseSchema = z.object({
   srsLeechThreshold: schedulingParamsShape.leechThreshold,
   srsEnableFuzz: schedulingParamsShape.enableFuzz,
   srsWeights: srsWeightsSchema.nullable(),
+  // Selects the scheduler/curve; read-only, changed only by the FSRS-7 migration.
+  srsModelVersion: srsModelVersionSchema,
   createdAt: z.date(),
   updatedAt: z.date(),
 });

package/src/schemas/srs.ts

@@ -3,6 +3,7 @@ import {
   activeScheduleStatusSchema,
   cardStateSchema,
   fsrsReviewLogSnapshotSchema,
+  fsrsMemoryStateSchema,
   reviewRatingSchema,
   scheduleStatusSchema,
   schedulingParamsSchema,
@@ -11,6 +12,7 @@ import {
 } from "@read-frog/definitions";
 import { z } from "zod";
 import { cardSchema } from "./card";
+import { notebaseSummarySchema } from "./notebase";
 import { timezoneSchema } from "./timezone";
 
 export { reviewRatingSchema, schedulingParamsSchema, SRS_REVIEW_DURATION_MS_MAX };
@@ -73,6 +75,26 @@ export type SrsScheduleStatusStatsInput = z.infer<typeof srsScheduleStatusStatsI
 export const srsScheduleStatusStatsOutputSchema = z.record(z.uuid(), srsScheduleStatusStatsSchema);
 export type SrsScheduleStatusStatsOutput = z.infer<typeof srsScheduleStatusStatsOutputSchema>;
 
+export const srsRecentNotebaseScheduleStatusStatsInputSchema = z
+  .object({
+    timezone: timezoneSchema,
+  })
+  .strict();
+export type SrsRecentNotebaseScheduleStatusStatsInput = z.infer<
+  typeof srsRecentNotebaseScheduleStatusStatsInputSchema
+>;
+
+/** Null when the user has no notebase yet. */
+export const srsRecentNotebaseScheduleStatusStatsOutputSchema = z
+  .object({
+    notebase: notebaseSummarySchema,
+    stats: srsScheduleStatusStatsSchema,
+  })
+  .nullable();
+export type SrsRecentNotebaseScheduleStatusStatsOutput = z.infer<
+  typeof srsRecentNotebaseScheduleStatusStatsOutputSchema
+>;
+
 export const srsManualCardStatusInputSchema = z
   .object({
     cardId: z.uuid(),
@@ -95,7 +117,9 @@ export const srsRevlogSchema = z.object({
   state: cardStateSchema,
   stability: z.number(),
   afterScheduleStatus: scheduleStatusSchema,
-  afterStability: z.number(),
+  afterMemoryState: fsrsMemoryStateSchema,
+  retentionDays90: z.number().nonnegative(),
+  afterRetentionDays90: z.number().nonnegative(),
   reviewedAt: z.coerce.date(),
   durationMs: z.number().int(),
   fsrsReviewLogSnapshot: fsrsReviewLogSnapshotSchema,