@read-frog/api-contract 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@orpc/contract": "^1.16.1",
-    "@read-frog/definitions": "0.13.0",
+    "@read-frog/definitions": "0.14.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

package/src/contracts/card.ts

@@ -2,6 +2,8 @@ import { defineAgentProcedure } from "./shared";
 import { oc } from "@orpc/contract";
 import { pickPublicErrorMap } from "#/public-errors";
 import {
+  CardDeleteInputSchema,
+  CardDeleteOutputSchema,
   CardGenerateInputSchema,
   CardGenerateOutputSchema,
   CardGetInputSchema,
@@ -11,6 +13,20 @@ import {
 } from "#/schemas/card";
 
 export const cardContract = {
+  delete: oc
+    .errors(
+      pickPublicErrorMap(
+        "CARD_NOT_FOUND",
+        "NOTEBASE_NOT_FOUND",
+        "CARD_DELETE_UNSUPPORTED",
+        "RESOURCE_UPDATE_CONFLICT",
+        "CELL_VALIDATION_FAILED",
+      ),
+    )
+    .route({ method: "DELETE", path: "/cards/{id}", summary: "Delete card", tags: ["Cards"] })
+    .input(CardDeleteInputSchema)
+    .output(CardDeleteOutputSchema),
+
   list: defineAgentProcedure({
     method: "GET",
     path: "/cards",

package/src/contracts/notebase-row.ts

@@ -92,7 +92,7 @@ export const notebaseRowContract = {
     path: "/notebase-rows/{notebaseRowId}",
     summary: "Update note",
     description:
-      "Merge supplied fields into an owned note, preserving omitted fields. Use null to clear a field. expectedUpdatedAt guards against editing stale data; reread on a modification conflict.",
+      "Merge supplied fields into an owned note, preserving omitted fields. Use null to clear a field. expectedUpdatedAt guards against editing stale data; reread on a modification conflict. In a cloze field, a deletion's number ({{c1::…}}) is its card's identity: keep the numbers of the deletions you keep, and leave any gaps for the save to close. Renumbering them yourself hands a card's review history to other text, and can delete it.",
     tags: ["Notebase Rows"],
   })
     .errors(pickPublicErrorMap("NOTEBASE_ROW_NOT_FOUND", "CELL_VALIDATION_FAILED"))
@@ -105,7 +105,7 @@ export const notebaseRowContract = {
     path: "/notebase-rows/batch",
     summary: "Update notes",
     description:
-      "Update 1–50 notes atomically in one owned notebase. Each row supplies its ID and fields to merge; omitted fields are preserved and null clears a field. Supply each note's expectedUpdatedAt to guard against stale edits. A missing row, invalid field or modification conflict rolls back the whole batch. Items are returned in input order.",
+      "Update 1–50 notes atomically in one owned notebase. Each row supplies its ID and fields to merge; omitted fields are preserved and null clears a field. Supply each note's expectedUpdatedAt to guard against stale edits. A missing row, invalid field or modification conflict rolls back the whole batch. Items are returned in input order. In a cloze field, a deletion's number ({{c1::…}}) is its card's identity: keep the numbers of the deletions you keep, and leave any gaps for the save to close. Renumbering them yourself hands a card's review history to other text, and can delete it.",
     tags: ["Notebase Rows"],
   })
     .errors(

package/src/public-errors.ts

@@ -21,6 +21,24 @@ export const CellValidationFailureReasonSchema = z.enum([
   "type_mismatch",
   "invalid_select_option",
   "invalid_date_format",
+  // A cloze deletion with a blank answer; receivedValue is the deletion as
+  // written (`{{c1::}}`).
+  "empty_cloze_answer",
+  // A cloze opening that never closes (unpaired braces, or no `}}`);
+  // receivedValue is the opening as written (`{{c1::`).
+  "unclosed_cloze",
+  // A cloze deletion whose ordinal list names no group (`{{c0::a}}`);
+  // receivedValue is the deletion as written.
+  "invalid_cloze_ordinal",
+  // A cloze deletion that cuts across a formula's delimiters (`\(a{{c1::b\) c}}`);
+  // receivedValue is the deletion as written.
+  "cloze_crosses_math",
+  // A cloze deletion in a formula that holds half of a `\left`/`\right` or
+  // `\begin`/`\end` pair; receivedValue is the deletion as written.
+  "cloze_splits_math_pair",
+  // More cloze groups in one note than CLOZE_MAX_GROUPS; receivedValue is
+  // the note's group count.
+  "too_many_cloze_groups",
 ]);
 export type CellValidationFailureReason = z.infer<typeof CellValidationFailureReasonSchema>;
 
@@ -42,6 +60,8 @@ export const CellValidationFailedDataSchema = z
     reason: CellValidationFailureReasonSchema,
     /** Index of the failing row within a batch input (createMany / updateMany / initialRows). */
     rowIndex: z.number().int().min(0).optional(),
+    /** The failing note, when the check ran over stored notes (a column type change). */
+    notebaseRowId: z.string().optional(),
   })
   .strict();
 export type CellValidationFailedData = z.infer<typeof CellValidationFailedDataSchema>;
@@ -103,6 +123,10 @@ export const SpeechDailyLimitReachedDataSchema = z.strictObject({
 });
 
 export const PUBLIC_APP_ERROR_DEFS = {
+  CARD_DELETE_UNSUPPORTED: {
+    message: "This card cannot be deleted independently of its note.",
+    status: 400,
+  },
   RESOURCE_UPDATE_CONFLICT: {
     message: "The resource changed. Read it again before updating.",
     status: 409,

package/src/schemas/card.ts

@@ -114,6 +114,16 @@ export type CardGetInput = z.infer<typeof CardGetInputSchema>;
 export const CardGetOutputSchema = renderedCardSchema;
 export type CardGetOutput = z.infer<typeof CardGetOutputSchema>;
 
+export const CardDeleteInputSchema = z.strictObject({
+  id: z.uuid(),
+  expectedVariantKey: z.string().min(1),
+  expectedRowUpdatedAt: expectedUpdatedAtSchema,
+});
+export type CardDeleteInput = z.infer<typeof CardDeleteInputSchema>;
+
+export const CardDeleteOutputSchema = z.object({ txid: z.number() });
+export type CardDeleteOutput = z.infer<typeof CardDeleteOutputSchema>;
+
 export const CardGenerateInputSchema = z.object({
   notebaseId: z.uuid(),
   templateId: z.uuid().optional(),

package/src/schemas/notebase-row.ts

@@ -1,5 +1,10 @@
 import { paginationShape, pageSchema } from "./pagination";
 import { deletionResultSchema, expectedUpdatedAtSchema } from "./resource-mutation";
+import {
+  noteCreatedViaSchema,
+  noteOriginInputSchema,
+  noteOriginSchema,
+} from "@read-frog/definitions";
 import { z } from "zod";
 
 export const notebaseRowCellsSchema = z.record(z.string(), z.unknown());
@@ -9,15 +14,38 @@ export const notebaseRowSchema = z.object({
   notebaseId: z.string(),
   cells: notebaseRowCellsSchema,
   position: z.number(),
+  origin: noteOriginSchema
+    .nullish()
+    .describe(
+      "Where the note's content came from, set when it was created: a web page (url, title), a book on the user's shelf (ebookId, its title then, and cfi, the EPUB location of the selection), or a video (url, title, seconds into it). Null when it has none, or when it was created before this was recorded.",
+    ),
+  createdVia: noteCreatedViaSchema
+    .nullish()
+    .describe(
+      'Which client created the note: "web", "extension", "mobile", "mcp" (with the MCP client\'s id and the name it registered under) or "unknown". Null for notes created before this was recorded.',
+    ),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 });
 export type NotebaseRow = z.infer<typeof notebaseRowSchema>;
 
+/**
+ * Where a new note's content came from; see `noteOriginInputSchema`. Optional
+ * metadata never costs the note: an origin that does not parse is dropped and
+ * the note is saved without one.
+ */
+export const notebaseRowOriginInputSchema = noteOriginInputSchema
+  .optional()
+  .catch(undefined)
+  .describe(
+    "Where the note's content came from: a web page or video by its http(s) URL, or a book on the user's shelf by its id. Stored once and never edited. Optional: an origin that cannot be used is left out and the note is still saved.",
+  );
+
 export const notebaseRowCreateDataSchema = z
   .object({
     id: z.uuid().optional(),
     cells: notebaseRowCellsSchema.optional(),
+    origin: notebaseRowOriginInputSchema,
   })
   .strict();
 export type NotebaseRowCreateData = z.infer<typeof notebaseRowCreateDataSchema>;
@@ -88,6 +116,8 @@ export const NotebaseRowUpdateOutputSchema = z.object({
   notebaseId: z.uuid(),
   cells: notebaseRowCellsSchema,
   position: z.number().int(),
+  origin: notebaseRowSchema.shape.origin,
+  createdVia: notebaseRowSchema.shape.createdVia,
   createdAt: z.date(),
   updatedAt: z.date(),
   txid: z.number(),

package/src/schemas/notebase.ts

@@ -8,7 +8,11 @@ import {
 } from "@read-frog/definitions";
 import { z } from "zod";
 import { notebaseColumnSchema } from "./notebase-column";
-import { NOTEBASE_ROW_CREATE_MANY_MAX_ROWS, notebaseRowSchema } from "./notebase-row";
+import {
+  NOTEBASE_ROW_CREATE_MANY_MAX_ROWS,
+  notebaseRowOriginInputSchema,
+  notebaseRowSchema,
+} from "./notebase-row";
 import { notebaseViewSchema } from "./notebase-view";
 
 export const NotebaseListInputSchema = z.object({});
@@ -55,6 +59,7 @@ const notebaseInitialRowSchema = z
   .object({
     id: z.uuid().optional(),
     cells: z.record(z.string(), z.unknown()),
+    origin: notebaseRowOriginInputSchema,
   })
   .strict();
 

package/src/schemas/web-sync.ts

@@ -26,6 +26,7 @@ export const webSyncOperationSchema = z.enum([
   "bury",
   "suspend",
   "deleteNote",
+  "deleteCard",
   // A synced collection's own mutation handlers.
   "insert",
   "update",