@read-frog/api-contract 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -24,15 +24,15 @@
     }
   },
   "dependencies": {
-    "@orpc/contract": "^1.15.2",
-    "@read-frog/definitions": "0.12.0",
-    "zod": "^4.6.5"
+    "@orpc/contract": "^1.16.1",
+    "@read-frog/definitions": "0.14.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@repo/tsdown-config": "0.0.0",
     "@repo/typescript-config": "0.0.0",
-    "@types/node": "^26.6.2",
-    "tsdown": "^0.23.0"
+    "@types/node": "^26.6.6",
+    "tsdown": "^0.23.4"
   },
   "scripts": {
     "build": "tsdown",

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/ebook.ts

@@ -23,7 +23,6 @@ const ebookProcedure = oc;
 
 export const ebookContract = {
   list: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED"))
     .route({
       method: "GET",
       path: "/ebooks",
@@ -34,7 +33,7 @@ export const ebookContract = {
     .output(ebookListOutputSchema),
 
   get: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_NOT_FOUND"))
+    .errors(pickPublicErrorMap("EBOOK_NOT_FOUND"))
     .route({
       method: "GET",
       path: "/ebooks/{id}",
@@ -45,9 +44,7 @@ export const ebookContract = {
     .output(ebookGetOutputSchema),
 
   requestUpload: ebookProcedure
-    .errors(
-      pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_LIMIT_EXCEEDED", "EBOOK_FILE_TOO_LARGE"),
-    )
+    .errors(pickPublicErrorMap("EBOOK_LIMIT_EXCEEDED", "EBOOK_FILE_TOO_LARGE"))
     .route({
       method: "POST",
       path: "/ebooks/uploads",
@@ -59,12 +56,7 @@ export const ebookContract = {
 
   finalizeUpload: ebookProcedure
     .errors(
-      pickPublicErrorMap(
-        "EBOOK_BETA_RESTRICTED",
-        "EBOOK_NOT_FOUND",
-        "EBOOK_UPLOAD_NOT_COMPLETED",
-        "EBOOK_FILE_TOO_LARGE",
-      ),
+      pickPublicErrorMap("EBOOK_NOT_FOUND", "EBOOK_UPLOAD_NOT_COMPLETED", "EBOOK_FILE_TOO_LARGE"),
     )
     .route({
       method: "POST",
@@ -76,7 +68,7 @@ export const ebookContract = {
     .output(ebookFinalizeUploadOutputSchema),
 
   getDownloadUrl: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_NOT_FOUND"))
+    .errors(pickPublicErrorMap("EBOOK_NOT_FOUND"))
     .route({
       method: "GET",
       path: "/ebooks/{id}/download-url",
@@ -87,7 +79,7 @@ export const ebookContract = {
     .output(ebookGetDownloadUrlOutputSchema),
 
   updateProgress: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_NOT_FOUND"))
+    .errors(pickPublicErrorMap("EBOOK_NOT_FOUND"))
     .route({
       method: "PATCH",
       path: "/ebooks/{id}/progress",
@@ -98,7 +90,7 @@ export const ebookContract = {
     .output(ebookUpdateProgressOutputSchema),
 
   rename: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_NOT_FOUND"))
+    .errors(pickPublicErrorMap("EBOOK_NOT_FOUND"))
     .route({
       method: "PATCH",
       path: "/ebooks/{id}",
@@ -109,7 +101,7 @@ export const ebookContract = {
     .output(ebookRenameOutputSchema),
 
   delete: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_NOT_FOUND"))
+    .errors(pickPublicErrorMap("EBOOK_NOT_FOUND"))
     .route({
       method: "DELETE",
       path: "/ebooks/{id}",

package/src/contracts/mcp-connection.ts

@@ -1,5 +1,7 @@
 import { oc } from "@orpc/contract";
+import { z } from "zod";
 import {
+  mcpCallUsageSchema,
   mcpConnectionListOutputSchema,
   mcpConnectionRevokeInputSchema,
   mcpConnectionRevokeOutputSchema,
@@ -23,4 +25,13 @@ export const mcpConnectionContract = {
     })
     .input(mcpConnectionRevokeInputSchema)
     .output(mcpConnectionRevokeOutputSchema),
+  usage: oc
+    .route({
+      method: "GET",
+      path: "/mcp-connections/usage",
+      summary: "Get the MCP tool calls the caller has used of their plan's daily limit",
+      tags: ["MCP Connections"],
+    })
+    .input(z.object({}).strict())
+    .output(mcpCallUsageSchema),
 };

package/src/contracts/media.ts

@@ -0,0 +1,60 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pickPublicErrorMap } from "#/public-errors";
+import {
+  mediaAssetIdInputSchema,
+  mediaAssetOutputSchema,
+  mediaRequestUploadInputSchema,
+  mediaRequestUploadOutputSchema,
+  mediaUsageOutputSchema,
+} from "#/schemas/media";
+
+export const mediaContract = {
+  requestUpload: oc
+    .errors(
+      pickPublicErrorMap("MEDIA_BETA_RESTRICTED", "MEDIA_FILE_TOO_LARGE", "MEDIA_QUOTA_EXCEEDED"),
+    )
+    .route({
+      method: "POST",
+      path: "/media/uploads",
+      summary: "Reserve space and get a signed upload URL for a media file",
+      tags: ["Media"],
+    })
+    .input(mediaRequestUploadInputSchema)
+    .output(mediaRequestUploadOutputSchema),
+
+  completeUpload: oc
+    .errors(
+      pickPublicErrorMap("MEDIA_BETA_RESTRICTED", "MEDIA_NOT_FOUND", "MEDIA_UPLOAD_NOT_COMPLETED"),
+    )
+    .route({
+      method: "POST",
+      path: "/media/{id}/complete",
+      summary: "Queue an uploaded media file for validation",
+      tags: ["Media"],
+    })
+    .input(mediaAssetIdInputSchema)
+    .output(mediaAssetOutputSchema),
+
+  get: oc
+    .errors(pickPublicErrorMap("MEDIA_BETA_RESTRICTED", "MEDIA_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/media/{id}",
+      summary: "Get a media asset and its upload status",
+      tags: ["Media"],
+    })
+    .input(mediaAssetIdInputSchema)
+    .output(mediaAssetOutputSchema),
+
+  usage: oc
+    .errors(pickPublicErrorMap("MEDIA_BETA_RESTRICTED"))
+    .route({
+      method: "GET",
+      path: "/media/usage",
+      summary: "Get the media space used, reserved and allowed",
+      tags: ["Media"],
+    })
+    .input(z.object({}).strict())
+    .output(mediaUsageOutputSchema),
+};

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/contracts/telemetry.ts

@@ -0,0 +1,17 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { reportWebSyncInputSchema } from "#/schemas/web-sync";
+
+export const telemetryContract = {
+  // Public: a page whose session ended still reports the streams that failed
+  // because of it.
+  reportWebSync: oc
+    .route({
+      method: "POST",
+      path: "/telemetry/web-sync",
+      summary: "Report problems the web app had keeping its synced data live",
+      tags: ["Telemetry"],
+    })
+    .input(reportWebSyncInputSchema)
+    .output(z.void()),
+};

package/src/index.ts

@@ -8,6 +8,7 @@ import { featureAccessContract } from "./contracts/feature-access";
 import { hostedAiContract } from "./contracts/hosted-ai";
 import { masteryGoalContract } from "./contracts/mastery-goal";
 import { mcpConnectionContract } from "./contracts/mcp-connection";
+import { mediaContract } from "./contracts/media";
 import { notebaseContract } from "./contracts/notebase";
 import { notebaseColumnContract } from "./contracts/notebase-column";
 import { notebaseRowContract } from "./contracts/notebase-row";
@@ -15,6 +16,7 @@ import { pdfTranslationContract } from "./contracts/pdf-translation";
 import { speechContract } from "./contracts/speech";
 import { srsContract } from "./contracts/srs";
 import { statsContract } from "./contracts/stats";
+import { telemetryContract } from "./contracts/telemetry";
 import { userContract } from "./contracts/user";
 import { videoTranscriptContract } from "./contracts/video-transcript";
 
@@ -28,6 +30,7 @@ export const contract = {
   hostedAi: hostedAiContract,
   masteryGoal: masteryGoalContract,
   mcpConnection: mcpConnectionContract,
+  media: mediaContract,
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
@@ -35,6 +38,7 @@ export const contract = {
   speech: speechContract,
   srs: srsContract,
   stats: statsContract,
+  telemetry: telemetryContract,
   user: userContract,
   videoTranscript: videoTranscriptContract,
 };
@@ -50,6 +54,7 @@ export * from "./schemas/ebook";
 export * from "./schemas/email-preferences";
 export * from "./schemas/feature-access";
 export * from "./schemas/hosted-ai";
+export * from "./schemas/media";
 export * from "./schemas/mastery-goal";
 export * from "./schemas/mcp-connection";
 export * from "./schemas/notebase";
@@ -65,6 +70,7 @@ export * from "./schemas/stats";
 export * from "./schemas/timezone";
 export * from "./schemas/user";
 export * from "./schemas/video-transcript";
+export * from "./schemas/web-sync";
 
 export * from "./schemas/pagination";
 export * from "./schemas/resource-mutation";

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,
@@ -289,10 +313,6 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Concurrent position conflict, please retry",
     status: 409,
   },
-  EBOOK_BETA_RESTRICTED: {
-    message: "Ebooks are currently in beta for selected accounts",
-    status: 403,
-  },
   EBOOK_NOT_FOUND: {
     message: "Ebook not found",
     status: 404,
@@ -309,6 +329,26 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Ebook upload has not been completed",
     status: 409,
   },
+  MEDIA_BETA_RESTRICTED: {
+    message: "Media uploads are currently in beta for selected accounts",
+    status: 403,
+  },
+  MEDIA_NOT_FOUND: {
+    message: "Media file not found",
+    status: 404,
+  },
+  MEDIA_FILE_TOO_LARGE: {
+    message: "Media file exceeds the maximum allowed size",
+    status: 413,
+  },
+  MEDIA_QUOTA_EXCEEDED: {
+    message: "Not enough media storage space left on your plan",
+    status: 403,
+  },
+  MEDIA_UPLOAD_NOT_COMPLETED: {
+    message: "Media upload has not been completed",
+    status: 409,
+  },
   // An email's unsubscribe or preferences link that does not verify, or whose
   // account no longer exists. The page asks the reader to sign in instead.
   EMAIL_LINK_INVALID: {

package/src/schemas/billing.ts

@@ -37,6 +37,22 @@ export const MCP_DAILY_CALL_LIMITS = {
   ultra: null,
 } as const satisfies Record<BillingPlan, number | null>;
 
+/**
+ * How many ebooks each plan may keep at once. Free keeps one, so it reads one
+ * book at a time; deleting a book frees its place for the next.
+ *
+ * Read by the API's upload gate AND by the website's copy (the pricing page),
+ * so the pages cannot promise books the server refuses.
+ *
+ * Companion edit when this changes: `account-and-plans` under
+ * `apps/www/content/docs/`, which states the numbers.
+ */
+export const EBOOK_LIMIT_BY_PLAN = {
+  free: 1,
+  pro: 10,
+  ultra: 80,
+} as const satisfies Record<BillingPlan, number>;
+
 // Plans a user can actively check out into (the free tier has no price).
 export const billingCheckoutPlanSchema = z.enum(["pro", "ultra"]);
 export type BillingCheckoutPlan = z.infer<typeof billingCheckoutPlanSchema>;

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/ebook.ts

@@ -77,6 +77,13 @@ export const ebookRequestUploadInputSchema = z
       })
       .strict()
       .optional(),
+    /**
+     * The client's key for this upload. Asking again with the same key, after
+     * an answer that never arrived or for a retry, returns the same pending
+     * book with fresh targets instead of reserving another place in the
+     * library's allowance.
+     */
+    uploadKey: z.uuid().optional(),
   })
   .strict();
 export type EbookRequestUploadInput = z.infer<typeof ebookRequestUploadInputSchema>;

package/src/schemas/mcp-connection.ts

@@ -26,3 +26,20 @@ export const mcpConnectionRevokeInputSchema = z.object({ clientId: z.string().mi
 export type McpConnectionRevokeInput = z.infer<typeof mcpConnectionRevokeInputSchema>;
 
 export const mcpConnectionRevokeOutputSchema = z.object({ clientId: z.string() }).strict();
+
+/**
+ * How many MCP tool calls the caller has used of their plan's
+ * `MCP_DAILY_CALL_LIMITS`, read without counting one. The window is 24 hours
+ * from the first call in it, not a calendar day.
+ */
+export const mcpCallUsageSchema = z
+  .object({
+    /** Calls used in the current window, at most `limit`. */
+    usedCalls: z.number().int().min(0),
+    /** null: the plan has no daily limit. */
+    limit: z.number().int().positive().nullable(),
+    /** When the current 24-hour window ends; null when no window is open or there is no limit. */
+    resetAt: z.iso.datetime().nullable(),
+  })
+  .strict();
+export type McpCallUsage = z.infer<typeof mcpCallUsageSchema>;

package/src/schemas/media.ts

@@ -0,0 +1,77 @@
+import { MEDIA_ASSET_STATUS_VALUES, MEDIA_CONTENT_TYPES } from "@read-frog/definitions";
+import { z } from "zod";
+
+export const mediaContentTypeSchema = z.enum(MEDIA_CONTENT_TYPES);
+export type MediaContentType = z.infer<typeof mediaContentTypeSchema>;
+
+export const mediaAssetStatusSchema = z.enum(MEDIA_ASSET_STATUS_VALUES);
+export type MediaAssetStatus = z.infer<typeof mediaAssetStatusSchema>;
+
+/** Why the worker rejected an upload. */
+export const mediaFailureCodeSchema = z.enum([
+  "unsupported_format",
+  "invalid_file",
+  "file_too_large",
+  "image_too_large",
+  "audio_too_long",
+  "quota_exceeded",
+  "processing_failed",
+]);
+export type MediaFailureCode = z.infer<typeof mediaFailureCodeSchema>;
+
+export const mediaAssetMetadataSchema = z.discriminatedUnion("kind", [
+  z
+    .object({ kind: z.literal("image"), width: z.number().int(), height: z.number().int() })
+    .strict(),
+  z.object({ kind: z.literal("audio"), durationMs: z.number().int() }).strict(),
+]);
+
+export const mediaAssetSchema = z
+  .object({
+    id: z.uuid(),
+    /** What a cell stores to reference the asset; null until it is ready. */
+    uri: z.string().nullable(),
+    status: mediaAssetStatusSchema,
+    contentType: z.string().nullable(),
+    fileByteSize: z.number().int(),
+    metadata: mediaAssetMetadataSchema.nullable(),
+    failureCode: mediaFailureCodeSchema.nullable(),
+    createdAt: z.coerce.date(),
+  })
+  .strict();
+export type MediaAsset = z.infer<typeof mediaAssetSchema>;
+
+export const mediaRequestUploadInputSchema = z
+  .object({
+    contentType: mediaContentTypeSchema,
+    // The exact size: the upload is signed for it, and storage refuses any other file.
+    byteSize: z.number().int().min(1),
+  })
+  .strict();
+export type MediaRequestUploadInput = z.infer<typeof mediaRequestUploadInputSchema>;
+
+export const mediaRequestUploadOutputSchema = z
+  .object({
+    assetId: z.uuid(),
+    /** A signed PUT: send the file to `url` with exactly `headers`. */
+    upload: z.object({ url: z.url(), headers: z.record(z.string(), z.string()) }).strict(),
+    expiresAt: z.coerce.date(),
+  })
+  .strict();
+export type MediaRequestUploadOutput = z.infer<typeof mediaRequestUploadOutputSchema>;
+
+export const mediaAssetIdInputSchema = z.object({ id: z.uuid() }).strict();
+export type MediaAssetIdInput = z.infer<typeof mediaAssetIdInputSchema>;
+
+export const mediaAssetOutputSchema = z.object({ asset: mediaAssetSchema }).strict();
+export type MediaAssetOutput = z.infer<typeof mediaAssetOutputSchema>;
+
+export const mediaUsageOutputSchema = z
+  .object({
+    usedBytes: z.number().int().min(0),
+    /** Held by uploads that are not done yet. */
+    reservedBytes: z.number().int().min(0),
+    limitBytes: z.number().int().min(0),
+  })
+  .strict();
+export type MediaUsageOutput = z.infer<typeof mediaUsageOutputSchema>;

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/srs.ts

@@ -154,7 +154,9 @@ export type SrsListCardRevlogsOutput = z.infer<typeof srsListCardRevlogsOutputSc
 export const srsReviewOutputSchema = z.object({
   card: cardSchema,
   revlog: srsRevlogSchema,
-  txid: z.number(),
+  // Null for an idempotent replay: it writes nothing, so no shape ever carries
+  // its transaction. Wait for the returned card and revlog instead.
+  txid: z.number().nullable(),
   // False when an idempotent replay returned an existing revlog instead of creating one.
   created: z.boolean(),
 });