@read-frog/api-contract 0.12.6 → 0.15.0

package/src/contracts/notebase.ts

@@ -1,4 +1,5 @@
-import { pickPublicErrorMap } from "#/public-errors"
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   NotebaseCreateInputSchema,
   NotebaseCreateOutputSchema,
@@ -8,25 +9,39 @@ import {
   NotebaseGetOutputSchema,
   NotebaseGetSchemaInputSchema,
   NotebaseGetSchemaOutputSchema,
+  NotebaseGetSummaryInputSchema,
+  NotebaseGetSummaryOutputSchema,
   NotebaseListInputSchema,
   NotebaseListOutputSchema,
   NotebaseUpdateInputSchema,
   NotebaseUpdateOutputSchema,
-} from "#/schemas/notebase"
-import { notebaseProcedure } from "./shared"
+} from "#/schemas/notebase";
+import { defineAgentProcedure } from "./shared";
 
 export const notebaseContract = {
-  list: notebaseProcedure
-    .route({
-      method: "GET",
-      path: "/notebases",
-      summary: "List notebases",
-      tags: ["Notebases"],
-    })
+  list: defineAgentProcedure({
+    method: "GET",
+    path: "/notebases",
+    summary: "List notebases",
+    description: "List the notebases (word books) owned by the current user.",
+    tags: ["Notebases"],
+  })
     .input(NotebaseListInputSchema)
     .output(NotebaseListOutputSchema),
 
-  get: notebaseProcedure
+  getSummary: defineAgentProcedure({
+    method: "GET",
+    path: "/notebases/{id}/summary",
+    summary: "Get notebase summary",
+    description:
+      "Read the name and public study settings of an owned notebase without loading note content.",
+    tags: ["Notebases"],
+  })
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .input(NotebaseGetSummaryInputSchema)
+    .output(NotebaseGetSummaryOutputSchema),
+
+  get: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
     .route({
       method: "GET",
@@ -37,47 +52,52 @@ export const notebaseContract = {
     .input(NotebaseGetInputSchema)
     .output(NotebaseGetOutputSchema),
 
-  getSchema: notebaseProcedure
+  getSchema: defineAgentProcedure({
+    method: "GET",
+    path: "/notebases/{id}/schema",
+    summary: "Get notebase schema",
+    description:
+      "Read an owned notebase name and field definitions, including field IDs, types and updatedAt timestamps. Does not return note content.",
+    tags: ["Notebases"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
-    .route({
-      method: "GET",
-      path: "/notebases/{id}/schema",
-      summary: "Get notebase schema",
-      tags: ["Notebases"],
-    })
     .input(NotebaseGetSchemaInputSchema)
     .output(NotebaseGetSchemaOutputSchema),
 
-  create: notebaseProcedure
+  create: defineAgentProcedure({
+    method: "POST",
+    path: "/notebases",
+    summary: "Create notebase",
+    description:
+      "Create an owned notebase with optional initial fields and notes. Client-provided entity IDs are supported; duplicate IDs produce a conflict.",
+    tags: ["Notebases"],
+  })
     .errors(pickPublicErrorMap("NOTE_LIMIT_EXCEEDED", "CELL_VALIDATION_FAILED"))
-    .route({
-      method: "POST",
-      path: "/notebases",
-      summary: "Create notebase",
-      tags: ["Notebases"],
-    })
+    .errors(pickPublicErrorMap("RESOURCE_ALREADY_EXISTS"))
     .input(NotebaseCreateInputSchema)
     .output(NotebaseCreateOutputSchema),
 
-  update: notebaseProcedure
+  update: defineAgentProcedure({
+    method: "PUT",
+    path: "/notebases/{id}",
+    summary: "Update notebase",
+    description:
+      "Update the supplied name or public study settings of an owned notebase, preserving omitted properties.",
+    tags: ["Notebases"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
-    .route({
-      method: "PUT",
-      path: "/notebases/{id}",
-      summary: "Update notebase",
-      tags: ["Notebases"],
-    })
     .input(NotebaseUpdateInputSchema)
     .output(NotebaseUpdateOutputSchema),
 
-  delete: notebaseProcedure
+  delete: defineAgentProcedure({
+    method: "DELETE",
+    path: "/notebases/{id}",
+    summary: "Delete notebase",
+    description:
+      "Permanently delete an owned notebase and its fields, notes, templates, cards and review records. Return the deleted notebase ID.",
+    tags: ["Notebases"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
-    .route({
-      method: "DELETE",
-      path: "/notebases/{id}",
-      summary: "Delete notebase",
-      tags: ["Notebases"],
-    })
     .input(NotebaseDeleteInputSchema)
     .output(NotebaseDeleteOutputSchema),
-}
+};

package/src/contracts/shared.ts

@@ -1,3 +1,22 @@
-import { oc } from "@orpc/contract"
+import type { Route } from "@orpc/contract";
+import { oc } from "@orpc/contract";
 
-export const notebaseProcedure = oc
+/**
+ * A documented business route shared by OpenAPI and agent-facing adapters.
+ * Both prose fields are required so adapters can reuse them without a second
+ * copy or an undefined fallback.
+ */
+export type AgentRoute = Route & { summary: string; description: string };
+
+/**
+ * Declares a procedure that is exposed to agents as an MCP tool, not only to
+ * the REST/OpenAPI surface.
+ *
+ * oRPC types `~orpc.route` as the widened `Route`, so `route.summary` reads back
+ * as `string | undefined` whatever is passed in. `$meta` is the only channel it
+ * keeps generic, so the prose is mirrored there and stays a required `string`
+ * for tool definitions. OpenAPI keeps reading `route`.
+ */
+export function defineAgentProcedure(route: AgentRoute) {
+  return oc.$meta({ summary: route.summary, description: route.description }).route(route);
+}

package/src/contracts/srs.ts

@@ -1,7 +1,13 @@
-import { pickPublicErrorMap } from "#/public-errors"
+import { defineAgentProcedure } from "./shared";
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
+  srsAcknowledgeOptimizerResultsInputSchema,
+  srsAcknowledgeOptimizerResultsOutputSchema,
   srsListCardRevlogsInputSchema,
   srsListCardRevlogsOutputSchema,
+  srsListUnreadOptimizerResultsInputSchema,
+  srsListUnreadOptimizerResultsOutputSchema,
   srsReviewInputSchema,
   srsReviewOutputSchema,
   srsRollbackReviewInputSchema,
@@ -12,87 +18,114 @@ import {
   srsSetCardBuriedOutputSchema,
   srsSetCardSuspendedInputSchema,
   srsSetCardSuspendedOutputSchema,
-} from "#/schemas/srs"
-import { notebaseProcedure } from "./shared"
+} from "#/schemas/srs";
 
 export const srsContract = {
-  scheduleStatusStats: notebaseProcedure
+  scheduleStatusStats: defineAgentProcedure({
+    method: "GET",
+    path: "/srs/schedule-status-stats",
+    summary: "Get study statistics",
+    description:
+      "Read existing study queue counts for owned notebases in the supplied timezone. Does not return note content or card faces.",
+    tags: ["SRS"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
-    .route({
-      method: "GET",
-      path: "/srs/schedule-status-stats",
-      summary: "List today schedule status stats for notebases",
-      tags: ["SRS"],
-    })
     .input(srsScheduleStatusStatsInputSchema)
     .output(srsScheduleStatusStatsOutputSchema),
-
-  listCardRevlogs: notebaseProcedure
-    .errors(pickPublicErrorMap("CARD_NOT_FOUND"))
+  listUnreadOptimizerResults: oc
     .route({
       method: "GET",
-      path: "/srs/cards/{cardId}/revlogs",
-      summary: "List complete review history for a card",
+      path: "/srs/optimizer-results/unread",
+      summary: "List unread applied SRS optimizer results",
       tags: ["SRS"],
     })
-    .input(srsListCardRevlogsInputSchema)
-    .output(srsListCardRevlogsOutputSchema),
+    .input(srsListUnreadOptimizerResultsInputSchema)
+    .output(srsListUnreadOptimizerResultsOutputSchema),
 
-  review: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "CARD_NOT_FOUND",
-      "CARD_NOT_REVIEWABLE",
-      "CARD_REVIEW_STATE_STALE",
-    ))
+  acknowledgeOptimizerResults: oc
     .route({
       method: "POST",
-      path: "/srs/review",
-      summary: "Review a card with SRS scheduling",
+      path: "/srs/optimizer-results/acknowledge",
+      summary: "Acknowledge current SRS optimizer results",
       tags: ["SRS"],
     })
+    .input(srsAcknowledgeOptimizerResultsInputSchema)
+    .output(srsAcknowledgeOptimizerResultsOutputSchema),
+
+  listCardRevlogs: defineAgentProcedure({
+    method: "GET",
+    path: "/srs/revlogs",
+    summary: "List review history",
+    description:
+      "Read owned review records, optionally filtered by notebase or card. Supports limit and offset pagination. Note content, card faces and rollback snapshots are excluded.",
+    tags: ["SRS"],
+  })
+    .errors(pickPublicErrorMap("CARD_NOT_FOUND", "NOTEBASE_NOT_FOUND"))
+    .input(srsListCardRevlogsInputSchema)
+    .output(srsListCardRevlogsOutputSchema),
+
+  review: defineAgentProcedure({
+    method: "POST",
+    path: "/srs/review",
+    summary: "Record review",
+    description:
+      "Submit one rating for a known owned card without a queue, session or prerequisite read. Existing SRS eligibility, scheduling and sibling rules apply. The optional id is the existing state-derived review ID, not an arbitrary UUID; calls without a stable id are not guaranteed to deduplicate.",
+    tags: ["SRS"],
+  })
+    .errors(pickPublicErrorMap("CARD_NOT_FOUND", "CARD_NOT_REVIEWABLE", "CARD_REVIEW_STATE_STALE"))
     .input(srsReviewInputSchema)
     .output(srsReviewOutputSchema),
-  rollbackReview: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "CARD_NOT_FOUND",
-      "CARD_REVIEW_ROLLBACK_UNAVAILABLE",
-    ))
-    .route({
-      method: "POST",
-      path: "/srs/review/rollback",
-      summary: "Roll back the latest SRS review for a card",
-      tags: ["SRS"],
-    })
+  rollbackReview: defineAgentProcedure({
+    method: "POST",
+    path: "/srs/review/rollback",
+    summary: "Undo review",
+    description:
+      "Undo the latest eligible review of one owned card, preserving existing SRS restrictions and sibling restoration. expectedReviewId guards against undoing an earlier review on a retry.",
+    tags: ["SRS"],
+  })
+    .errors(
+      pickPublicErrorMap(
+        "CARD_NOT_FOUND",
+        "CARD_REVIEW_ROLLBACK_UNAVAILABLE",
+        "CARD_REVIEW_STATE_STALE",
+      ),
+    )
     .input(srsRollbackReviewInputSchema)
     .output(srsRollbackReviewOutputSchema),
-  setCardBuried: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "CARD_NOT_FOUND",
-      "CARD_ALREADY_BURIED",
-      "CARD_NOT_BURIED",
-      "CARD_STATUS_CHANGE_UNAVAILABLE",
-    ))
-    .route({
-      method: "POST",
-      path: "/srs/card/bury",
-      summary: "Manually bury or unbury a card",
-      tags: ["SRS"],
-    })
+  setCardBuried: defineAgentProcedure({
+    method: "POST",
+    path: "/srs/card/bury",
+    summary: "Set card buried",
+    description:
+      "Bury or unbury one owned card. enabled=true buries and enabled=false unburies it. Existing state-change rules apply.",
+    tags: ["SRS"],
+  })
+    .errors(
+      pickPublicErrorMap(
+        "CARD_NOT_FOUND",
+        "CARD_ALREADY_BURIED",
+        "CARD_NOT_BURIED",
+        "CARD_STATUS_CHANGE_UNAVAILABLE",
+      ),
+    )
     .input(srsSetCardBuriedInputSchema)
     .output(srsSetCardBuriedOutputSchema),
-  setCardSuspended: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "CARD_NOT_FOUND",
-      "CARD_ALREADY_SUSPENDED",
-      "CARD_NOT_SUSPENDED",
-      "CARD_STATUS_CHANGE_UNAVAILABLE",
-    ))
-    .route({
-      method: "POST",
-      path: "/srs/card/suspend",
-      summary: "Manually suspend or unsuspend a card",
-      tags: ["SRS"],
-    })
+  setCardSuspended: defineAgentProcedure({
+    method: "POST",
+    path: "/srs/card/suspend",
+    summary: "Set card suspended",
+    description:
+      "Suspend or resume one owned card. enabled=true suspends and enabled=false resumes it. Existing state-change rules apply.",
+    tags: ["SRS"],
+  })
+    .errors(
+      pickPublicErrorMap(
+        "CARD_NOT_FOUND",
+        "CARD_ALREADY_SUSPENDED",
+        "CARD_NOT_SUSPENDED",
+        "CARD_STATUS_CHANGE_UNAVAILABLE",
+      ),
+    )
     .input(srsSetCardSuspendedInputSchema)
     .output(srsSetCardSuspendedOutputSchema),
-}
+};

package/src/contracts/stats.ts

@@ -1,13 +1,11 @@
-import { pickPublicErrorMap } from "#/public-errors"
-import { notebaseRowGrowthStatsOutputSchema } from "#/schemas/notebase-stats"
-import {
-  srsMemoryGrowthStatsOutputSchema,
-} from "#/schemas/srs-stats"
-import { activityStatsOutputSchema, statsInputSchema } from "#/schemas/stats"
-import { notebaseProcedure } from "./shared"
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
+import { notebaseRowGrowthStatsOutputSchema } from "#/schemas/notebase-stats";
+import { srsMemoryGrowthStatsOutputSchema } from "#/schemas/srs-stats";
+import { activityStatsOutputSchema, statsInputSchema } from "#/schemas/stats";
 
 export const statsContract = {
-  activity: notebaseProcedure
+  activity: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
     .route({
       method: "GET",
@@ -18,7 +16,7 @@ export const statsContract = {
     .input(statsInputSchema)
     .output(activityStatsOutputSchema),
 
-  srsMemoryGrowth: notebaseProcedure
+  srsMemoryGrowth: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
     .route({
       method: "GET",
@@ -29,7 +27,7 @@ export const statsContract = {
     .input(statsInputSchema)
     .output(srsMemoryGrowthStatsOutputSchema),
 
-  notebaseRowGrowth: notebaseProcedure
+  notebaseRowGrowth: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
     .route({
       method: "GET",
@@ -39,4 +37,4 @@ export const statsContract = {
     })
     .input(statsInputSchema)
     .output(notebaseRowGrowthStatsOutputSchema),
-}
+};

package/src/contracts/user.ts

@@ -1,10 +1,10 @@
-import { oc } from "@orpc/contract"
+import { oc } from "@orpc/contract";
 import {
   userEnsureTimezoneInputSchema,
   userEnsureTimezoneOutputSchema,
   userUpdateTimezoneInputSchema,
   userUpdateTimezoneOutputSchema,
-} from "#/schemas/user"
+} from "#/schemas/user";
 
 export const userContract = {
   ensureTimezone: oc
@@ -25,4 +25,4 @@ export const userContract = {
     })
     .input(userUpdateTimezoneInputSchema)
     .output(userUpdateTimezoneOutputSchema),
-}
+};

package/src/contracts/video-transcript.ts

@@ -1,16 +1,23 @@
-import { oc } from "@orpc/contract"
-import { pickPublicErrorMap } from "#/public-errors"
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   videoTranscriptCreateInputSchema,
   videoTranscriptGetInputSchema,
   videoTranscriptResourceSchema,
   videoTranscriptSubtitlesSchema,
   videoTranscriptUsageSchema,
-} from "#/schemas/video-transcript"
+} from "#/schemas/video-transcript";
 
 export const videoTranscriptContract = {
   create: oc
-    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPTION_QUOTA_EXCEEDED"))
+    .errors(
+      pickPublicErrorMap(
+        "VIDEO_TRANSCRIPTION_QUOTA_EXCEEDED",
+        "VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED",
+        "VIDEO_TRANSCRIPTION_PAYMENT_REQUIRED",
+        "VIDEO_TRANSCRIPTION_UNSUPPORTED_LENGTH",
+      ),
+    )
     .route({
       method: "POST",
       path: "/video-transcripts",
@@ -28,7 +35,9 @@ export const videoTranscriptContract = {
     })
     .output(videoTranscriptUsageSchema),
   get: oc
-    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND"))
+    .errors(
+      pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND", "VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED"),
+    )
     .route({
       method: "GET",
       path: "/video-transcripts/{id}",
@@ -38,7 +47,13 @@ export const videoTranscriptContract = {
     .input(videoTranscriptGetInputSchema)
     .output(videoTranscriptResourceSchema),
   getSubtitles: oc
-    .errors(pickPublicErrorMap("VIDEO_TRANSCRIPT_NOT_FOUND", "VIDEO_TRANSCRIPT_NOT_READY"))
+    .errors(
+      pickPublicErrorMap(
+        "VIDEO_TRANSCRIPT_NOT_FOUND",
+        "VIDEO_TRANSCRIPT_NOT_READY",
+        "VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED",
+      ),
+    )
     .route({
       method: "GET",
       path: "/video-transcripts/{id}/subtitles",
@@ -47,4 +62,4 @@ export const videoTranscriptContract = {
     })
     .input(videoTranscriptGetInputSchema)
     .output(videoTranscriptSubtitlesSchema),
-}
+};

package/src/index.ts

@@ -1,17 +1,17 @@
-import type { ContractRouterClient } from "@orpc/contract"
-import { betaAccessContract } from "./contracts/beta-access"
-import { billingContract } from "./contracts/billing"
-import { cardContract } from "./contracts/card"
-import { cardTemplateContract } from "./contracts/card-template"
-import { ebookContract } from "./contracts/ebook"
-import { hostedAiContract } from "./contracts/hosted-ai"
-import { notebaseContract } from "./contracts/notebase"
-import { notebaseColumnContract } from "./contracts/notebase-column"
-import { notebaseRowContract } from "./contracts/notebase-row"
-import { srsContract } from "./contracts/srs"
-import { statsContract } from "./contracts/stats"
-import { userContract } from "./contracts/user"
-import { videoTranscriptContract } from "./contracts/video-transcript"
+import type { ContractRouterClient } from "@orpc/contract";
+import { betaAccessContract } from "./contracts/beta-access";
+import { billingContract } from "./contracts/billing";
+import { cardContract } from "./contracts/card";
+import { cardTemplateContract } from "./contracts/card-template";
+import { ebookContract } from "./contracts/ebook";
+import { hostedAiContract } from "./contracts/hosted-ai";
+import { notebaseContract } from "./contracts/notebase";
+import { notebaseColumnContract } from "./contracts/notebase-column";
+import { notebaseRowContract } from "./contracts/notebase-row";
+import { srsContract } from "./contracts/srs";
+import { statsContract } from "./contracts/stats";
+import { userContract } from "./contracts/user";
+import { videoTranscriptContract } from "./contracts/video-transcript";
 
 export const contract = {
   betaAccess: betaAccessContract,
@@ -27,24 +27,28 @@ export const contract = {
   stats: statsContract,
   user: userContract,
   videoTranscript: videoTranscriptContract,
-}
+};
 
-export type ORPCRouterClient = ContractRouterClient<typeof contract>
+export type ORPCRouterClient = ContractRouterClient<typeof contract>;
 
-export * from "./public-errors"
-export * from "./schemas/beta-access"
-export * from "./schemas/billing"
-export * from "./schemas/card"
-export * from "./schemas/ebook"
-export * from "./schemas/hosted-ai"
-export * from "./schemas/notebase"
-export * from "./schemas/notebase-column"
-export * from "./schemas/notebase-row"
-export * from "./schemas/notebase-stats"
-export * from "./schemas/notebase-view"
-export * from "./schemas/srs"
-export * from "./schemas/srs-stats"
-export * from "./schemas/stats"
-export * from "./schemas/timezone"
-export * from "./schemas/user"
-export * from "./schemas/video-transcript"
+export { type AgentRoute, defineAgentProcedure } from "./contracts/shared";
+export * from "./public-errors";
+export * from "./schemas/beta-access";
+export * from "./schemas/billing";
+export * from "./schemas/card";
+export * from "./schemas/ebook";
+export * from "./schemas/hosted-ai";
+export * from "./schemas/notebase";
+export * from "./schemas/notebase-column";
+export * from "./schemas/notebase-row";
+export * from "./schemas/notebase-stats";
+export * from "./schemas/notebase-view";
+export * from "./schemas/srs";
+export * from "./schemas/srs-stats";
+export * from "./schemas/stats";
+export * from "./schemas/timezone";
+export * from "./schemas/user";
+export * from "./schemas/video-transcript";
+
+export * from "./schemas/pagination";
+export * from "./schemas/resource-mutation";