@read-frog/api-contract 0.12.6 → 0.15.0

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@read-frog/api-contract",
-  "type": "module",
-  "version": "0.12.6",
+  "version": "0.15.0",
   "private": false,
   "repository": {
     "type": "git",
     "url": "https://github.com/mengxi-ream/read-frog-monorepo",
     "directory": "packages/api-contract"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "imports": {
     "#/*": "./src/*.ts"
   },
@@ -17,21 +23,14 @@
       "import": "./dist/index.js"
     }
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "src"
-  ],
   "dependencies": {
     "@orpc/contract": "^1.14.6",
-    "zod": "^4.4.3",
-    "@read-frog/definitions": "0.4.4"
+    "zod": "^4.5.4",
+    "@read-frog/definitions": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
-    "tsdown": "^0.22.3",
-    "@repo/eslint-config": "0.0.1",
+    "tsdown": "^0.22.14",
     "@repo/tsdown-config": "0.0.0",
     "@repo/typescript-config": "0.0.0"
   },
@@ -40,7 +39,9 @@
     "dev": "tsdown --watch",
     "build:publish": "tsdown",
     "type-check": "tsc --noEmit",
-    "lint": "eslint . --max-warnings 0",
-    "lint:fix": "eslint --fix --max-warnings 0"
+    "fmt": "oxfmt --config ../../.oxfmtrc.json --write --no-error-on-unmatched-pattern .",
+    "fmt:check": "oxfmt --config ../../.oxfmtrc.json --check --no-error-on-unmatched-pattern .",
+    "lint": "oxlint --config ../../.oxlintrc.json --type-aware --deny-warnings --report-unused-disable-directives-severity=error --no-error-on-unmatched-pattern .",
+    "lint:fix": "oxlint --config ../../.oxlintrc.json --type-aware --fix --deny-warnings --report-unused-disable-directives-severity=error --no-error-on-unmatched-pattern ."
   }
 }

package/src/contracts/beta-access.ts

@@ -1,8 +1,5 @@
-import { oc } from "@orpc/contract"
-import {
-  BetaAccessStatusInputSchema,
-  BetaAccessStatusOutputSchema,
-} from "#/schemas/beta-access"
+import { oc } from "@orpc/contract";
+import { BetaAccessStatusInputSchema, BetaAccessStatusOutputSchema } from "#/schemas/beta-access";
 
 export const betaAccessContract = {
   status: oc
@@ -14,4 +11,4 @@ export const betaAccessContract = {
     })
     .input(BetaAccessStatusInputSchema)
     .output(BetaAccessStatusOutputSchema),
-}
+};

package/src/contracts/billing.ts

@@ -1,12 +1,12 @@
-import { oc } from "@orpc/contract"
-import { pickPublicErrorMap } from "#/public-errors"
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   billingCancelScheduledChangeOutputSchema,
   billingCreateCheckoutSessionInputSchema,
   billingCreateCustomerPortalSessionInputSchema,
   billingSessionUrlOutputSchema,
   billingStatusSchema,
-} from "#/schemas/billing"
+} from "#/schemas/billing";
 
 const billingProcedure = oc.errors(
   pickPublicErrorMap(
@@ -15,7 +15,7 @@ const billingProcedure = oc.errors(
     "BILLING_PASS_ACTIVE",
     "BILLING_CHANGE_SCHEDULED",
   ),
-)
+);
 
 export const billingContract = {
   status: billingProcedure
@@ -52,4 +52,4 @@ export const billingContract = {
       tags: ["Billing"],
     })
     .output(billingCancelScheduledChangeOutputSchema),
-}
+};

package/src/contracts/card-template.ts

@@ -1,4 +1,5 @@
-import { pickPublicErrorMap } from "#/public-errors"
+import { defineAgentProcedure } from "./shared";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   CardTemplateCreateInputSchema,
   CardTemplateCreateOutputSchema,
@@ -10,62 +11,67 @@ import {
   CardTemplateListOutputSchema,
   CardTemplateUpdateInputSchema,
   CardTemplateUpdateOutputSchema,
-} from "#/schemas/card"
-import { notebaseProcedure } from "./shared"
+} from "#/schemas/card";
 
 export const cardTemplateContract = {
-  list: notebaseProcedure
+  list: defineAgentProcedure({
+    method: "GET",
+    path: "/card-templates",
+    summary: "List card templates",
+    description:
+      "List owned card templates, optionally filtered by notebase. Supports limit and offset pagination.",
+    tags: ["Card Templates"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
-    .route({
-      method: "GET",
-      path: "/card-templates",
-      summary: "List card templates",
-      tags: ["Card Templates"],
-    })
     .input(CardTemplateListInputSchema)
     .output(CardTemplateListOutputSchema),
 
-  get: notebaseProcedure
+  get: defineAgentProcedure({
+    method: "GET",
+    path: "/card-templates/{id}",
+    summary: "Get card template",
+    description: "Read the complete definition and updatedAt timestamp of an owned card template.",
+    tags: ["Card Templates"],
+  })
     .errors(pickPublicErrorMap("CARD_TEMPLATE_NOT_FOUND"))
-    .route({
-      method: "GET",
-      path: "/card-templates/{id}",
-      summary: "Get card template",
-      tags: ["Card Templates"],
-    })
     .input(CardTemplateGetInputSchema)
     .output(CardTemplateGetOutputSchema),
 
-  create: notebaseProcedure
+  create: defineAgentProcedure({
+    method: "POST",
+    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.",
+    tags: ["Card Templates"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS"))
-    .route({
-      method: "POST",
-      path: "/card-templates",
-      summary: "Create card template",
-      tags: ["Card Templates"],
-    })
+    .errors(pickPublicErrorMap("RESOURCE_ALREADY_EXISTS"))
     .input(CardTemplateCreateInputSchema)
     .output(CardTemplateCreateOutputSchema),
 
-  update: notebaseProcedure
+  update: defineAgentProcedure({
+    method: "PATCH",
+    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.",
+    tags: ["Card Templates"],
+  })
     .errors(pickPublicErrorMap("CARD_TEMPLATE_NOT_FOUND", "CARD_TEMPLATE_INVALID_NOTEBASE_COLUMNS"))
-    .route({
-      method: "PATCH",
-      path: "/card-templates/{id}",
-      summary: "Update card template",
-      tags: ["Card Templates"],
-    })
+    .errors(pickPublicErrorMap("RESOURCE_UPDATE_CONFLICT"))
     .input(CardTemplateUpdateInputSchema)
     .output(CardTemplateUpdateOutputSchema),
 
-  delete: notebaseProcedure
+  delete: defineAgentProcedure({
+    method: "DELETE",
+    path: "/card-templates/{id}",
+    summary: "Delete card template",
+    description:
+      "Permanently delete an owned template and its generated cards and review records. Source notes are preserved.",
+    tags: ["Card Templates"],
+  })
     .errors(pickPublicErrorMap("CARD_TEMPLATE_NOT_FOUND"))
-    .route({
-      method: "DELETE",
-      path: "/card-templates/{id}",
-      summary: "Delete card template",
-      tags: ["Card Templates"],
-    })
     .input(CardTemplateDeleteInputSchema)
     .output(CardTemplateDeleteOutputSchema),
-}
+};

package/src/contracts/card.ts

@@ -1,4 +1,6 @@
-import { pickPublicErrorMap } from "#/public-errors"
+import { defineAgentProcedure } from "./shared";
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   CardGenerateInputSchema,
   CardGenerateOutputSchema,
@@ -6,33 +8,34 @@ import {
   CardGetOutputSchema,
   CardListInputSchema,
   CardListOutputSchema,
-} from "#/schemas/card"
-import { notebaseProcedure } from "./shared"
+} from "#/schemas/card";
 
 export const cardContract = {
-  list: notebaseProcedure
+  list: defineAgentProcedure({
+    method: "GET",
+    path: "/cards",
+    summary: "List cards",
+    description:
+      "Browse owned cards with rendered fronts, backs, source IDs and learning state. Optionally filter by notebase, template or scheduleStatus. Supports limit and offset pagination.",
+    tags: ["Cards"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
-    .route({
-      method: "GET",
-      path: "/cards",
-      summary: "List rendered cards",
-      tags: ["Cards"],
-    })
     .input(CardListInputSchema)
     .output(CardListOutputSchema),
 
-  get: notebaseProcedure
+  get: defineAgentProcedure({
+    method: "GET",
+    path: "/cards/{id}",
+    summary: "Get card",
+    description:
+      "Read one owned card with its rendered front, back, source IDs and learning state.",
+    tags: ["Cards"],
+  })
     .errors(pickPublicErrorMap("CARD_NOT_FOUND"))
-    .route({
-      method: "GET",
-      path: "/cards/{id}",
-      summary: "Get rendered card",
-      tags: ["Cards"],
-    })
     .input(CardGetInputSchema)
     .output(CardGetOutputSchema),
 
-  generate: notebaseProcedure
+  generate: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CARD_TEMPLATE_NOT_FOUND"))
     .route({
       method: "POST",
@@ -42,4 +45,4 @@ export const cardContract = {
     })
     .input(CardGenerateInputSchema)
     .output(CardGenerateOutputSchema),
-}
+};

package/src/contracts/ebook.ts

@@ -1,5 +1,5 @@
-import { oc } from "@orpc/contract"
-import { pickPublicErrorMap } from "#/public-errors"
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   ebookDeleteInputSchema,
   ebookDeleteOutputSchema,
@@ -17,9 +17,9 @@ import {
   ebookRequestUploadOutputSchema,
   ebookUpdateProgressInputSchema,
   ebookUpdateProgressOutputSchema,
-} from "#/schemas/ebook"
+} from "#/schemas/ebook";
 
-const ebookProcedure = oc
+const ebookProcedure = oc;
 
 export const ebookContract = {
   list: ebookProcedure
@@ -56,12 +56,14 @@ export const ebookContract = {
     .output(ebookRequestUploadOutputSchema),
 
   finalizeUpload: ebookProcedure
-    .errors(pickPublicErrorMap(
-      "EBOOK_BETA_RESTRICTED",
-      "EBOOK_NOT_FOUND",
-      "EBOOK_UPLOAD_NOT_COMPLETED",
-      "EBOOK_FILE_TOO_LARGE",
-    ))
+    .errors(
+      pickPublicErrorMap(
+        "EBOOK_BETA_RESTRICTED",
+        "EBOOK_NOT_FOUND",
+        "EBOOK_UPLOAD_NOT_COMPLETED",
+        "EBOOK_FILE_TOO_LARGE",
+      ),
+    )
     .route({
       method: "POST",
       path: "/ebooks/{ebookId}/finalize",
@@ -114,4 +116,4 @@ export const ebookContract = {
     })
     .input(ebookDeleteInputSchema)
     .output(ebookDeleteOutputSchema),
-}
+};

package/src/contracts/hosted-ai.ts

@@ -1,5 +1,5 @@
-import { eventIterator, oc } from "@orpc/contract"
-import { pickPublicErrorMap } from "#/public-errors"
+import { eventIterator, oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   HostedAiNoteSuggestionStreamInputSchema,
   HostedAiStatusInputSchema,
@@ -7,12 +7,12 @@ import {
   HostedAiStreamPartSchema,
   HostedAiStreamStructuredObjectInputSchema,
   HostedAiStreamTextInputSchema,
-} from "#/schemas/hosted-ai"
+} from "#/schemas/hosted-ai";
 
 const hostedAiStreamErrors = pickPublicErrorMap(
   "HOSTED_AI_TIER_RESTRICTED",
   "HOSTED_AI_QUOTA_EXHAUSTED",
-)
+);
 
 export const hostedAiContract = {
   status: oc
@@ -130,4 +130,4 @@ export const hostedAiContract = {
       .output(eventIterator(HostedAiStreamPartSchema))
       .errors(hostedAiStreamErrors),
   },
-}
+};

package/src/contracts/notebase-column.ts

@@ -1,4 +1,6 @@
-import { pickPublicErrorMap } from "#/public-errors"
+import { defineAgentProcedure } from "./shared";
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   NotebaseColumnCreateInputSchema,
   NotebaseColumnCreateOutputSchema,
@@ -8,49 +10,55 @@ import {
   NotebaseColumnReorderOutputSchema,
   NotebaseColumnUpdateInputSchema,
   NotebaseColumnUpdateOutputSchema,
-} from "#/schemas/notebase-column"
-import { notebaseProcedure } from "./shared"
+} from "#/schemas/notebase-column";
 
 export const notebaseColumnContract = {
-  create: notebaseProcedure
+  create: defineAgentProcedure({
+    method: "POST",
+    path: "/notebase-columns",
+    summary: "Create notebase field",
+    description:
+      "Create a field in an owned notebase. The returned field ID is used as a key in note cells.",
+    tags: ["Notebase Columns"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
-    .route({
-      method: "POST",
-      path: "/notebase-columns",
-      summary: "Create notebase column",
-      tags: ["Notebase Columns"],
-    })
+    .errors(pickPublicErrorMap("RESOURCE_ALREADY_EXISTS"))
     .input(NotebaseColumnCreateInputSchema)
     .output(NotebaseColumnCreateOutputSchema),
 
-  update: notebaseProcedure
+  update: defineAgentProcedure({
+    method: "PATCH",
+    path: "/notebase-columns/{notebaseColumnId}",
+    summary: "Update notebase field",
+    description:
+      "Update an owned field without changing its type. Removing select options clears affected note values. expectedUpdatedAt guards against editing stale data.",
+    tags: ["Notebase Columns"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_COLUMN_NOT_FOUND"))
-    .route({
-      method: "PATCH",
-      path: "/notebase-columns/{notebaseColumnId}",
-      summary: "Update notebase column",
-      tags: ["Notebase Columns"],
-    })
+    .errors(pickPublicErrorMap("RESOURCE_UPDATE_CONFLICT", "FIELD_TYPE_CHANGE_UNSUPPORTED"))
     .input(NotebaseColumnUpdateInputSchema)
     .output(NotebaseColumnUpdateOutputSchema),
 
-  delete: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "NOTEBASE_COLUMN_NOT_FOUND",
-      "PRIMARY_NOTEBASE_COLUMN_DELETE_NOT_ALLOWED",
-      "CARD_TEMPLATE_NOTEBASE_COLUMN_IN_USE",
-      "CONCURRENT_POSITION_CONFLICT",
-    ))
-    .route({
-      method: "DELETE",
-      path: "/notebase-columns/{notebaseColumnId}",
-      summary: "Delete notebase column",
-      tags: ["Notebase Columns"],
-    })
+  delete: defineAgentProcedure({
+    method: "DELETE",
+    path: "/notebase-columns/{notebaseColumnId}",
+    summary: "Delete notebase field",
+    description:
+      "Delete an owned field and remove its values from notes. Primary fields and fields referenced by templates cannot be deleted.",
+    tags: ["Notebase Columns"],
+  })
+    .errors(
+      pickPublicErrorMap(
+        "NOTEBASE_COLUMN_NOT_FOUND",
+        "PRIMARY_NOTEBASE_COLUMN_DELETE_NOT_ALLOWED",
+        "CARD_TEMPLATE_NOTEBASE_COLUMN_IN_USE",
+        "CONCURRENT_POSITION_CONFLICT",
+      ),
+    )
     .input(NotebaseColumnDeleteInputSchema)
     .output(NotebaseColumnDeleteOutputSchema),
 
-  reorder: notebaseProcedure
+  reorder: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
     .route({
       method: "POST",
@@ -60,4 +68,4 @@ export const notebaseColumnContract = {
     })
     .input(NotebaseColumnReorderInputSchema)
     .output(NotebaseColumnReorderOutputSchema),
-}
+};

package/src/contracts/notebase-row.ts

@@ -1,4 +1,12 @@
-import { pickPublicErrorMap } from "#/public-errors"
+import { defineAgentProcedure } from "./shared";
+import {
+  NotebaseRowListInputSchema,
+  NotebaseRowListOutputSchema,
+  NotebaseRowGetInputSchema,
+  NotebaseRowGetOutputSchema,
+} from "#/schemas/notebase-row";
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
 import {
   NotebaseRowCreateInputSchema,
   NotebaseRowCreateManyInputSchema,
@@ -10,65 +18,97 @@ import {
   NotebaseRowReorderOutputSchema,
   NotebaseRowUpdateInputSchema,
   NotebaseRowUpdateOutputSchema,
-} from "#/schemas/notebase-row"
-import { notebaseProcedure } from "./shared"
+} from "#/schemas/notebase-row";
 
 export const notebaseRowContract = {
-  create: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "NOTEBASE_NOT_FOUND",
-      "CELL_VALIDATION_FAILED",
-      "CONCURRENT_POSITION_CONFLICT",
-      "NOTE_LIMIT_EXCEEDED",
-    ))
-    .route({
-      method: "POST",
-      path: "/notebase-rows",
-      summary: "Create notebase row",
-      tags: ["Notebase Rows"],
-    })
+  list: defineAgentProcedure({
+    method: "GET",
+    path: "/notebase-rows",
+    summary: "List or search notes",
+    description:
+      "List or search owned notes, optionally within one notebase. Supply query to search; omit it to browse, which returns every note in scope rather than a filtered set. Searching requires notebaseId and covers that one notebase, so cover several by listing them first and calling this once per notebase. The query filter is at least two characters, matches a literal case-insensitive substring, and only searches fields of type string, so values in number, boolean, date and select fields are never matched. Supports limit and offset pagination.",
+    tags: ["Notebase Rows"],
+  })
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .input(NotebaseRowListInputSchema)
+    .output(NotebaseRowListOutputSchema),
+  get: defineAgentProcedure({
+    method: "GET",
+    path: "/notebase-rows/{id}",
+    summary: "Get note",
+    description:
+      "Read one owned note with field-ID values and the updatedAt timestamp used for modification checks.",
+    tags: ["Notebase Rows"],
+  })
+    .errors(pickPublicErrorMap("NOTEBASE_ROW_NOT_FOUND"))
+    .input(NotebaseRowGetInputSchema)
+    .output(NotebaseRowGetOutputSchema),
+  create: defineAgentProcedure({
+    method: "POST",
+    path: "/notebase-rows",
+    summary: "Create note",
+    description:
+      "Create a note in an owned notebase using field IDs and their declared value types. Existing templates generate cards. A duplicate entity ID produces a conflict.",
+    tags: ["Notebase Rows"],
+  })
+    .errors(
+      pickPublicErrorMap(
+        "NOTEBASE_NOT_FOUND",
+        "CELL_VALIDATION_FAILED",
+        "CONCURRENT_POSITION_CONFLICT",
+        "NOTE_LIMIT_EXCEEDED",
+      ),
+    )
+    .errors(pickPublicErrorMap("RESOURCE_ALREADY_EXISTS"))
     .input(NotebaseRowCreateInputSchema)
     .output(NotebaseRowCreateOutputSchema),
 
-  createMany: notebaseProcedure
-    .errors(pickPublicErrorMap(
-      "NOTEBASE_NOT_FOUND",
-      "CELL_VALIDATION_FAILED",
-      "CONCURRENT_POSITION_CONFLICT",
-      "NOTE_LIMIT_EXCEEDED",
-    ))
-    .route({
-      method: "POST",
-      path: "/notebase-rows/batch",
-      summary: "Create notebase rows in a single transaction",
-      tags: ["Notebase Rows"],
-    })
+  createMany: defineAgentProcedure({
+    method: "POST",
+    path: "/notebase-rows/batch",
+    summary: "Create notes",
+    description:
+      "Create 1–50 notes atomically in one owned notebase. Cells use field IDs and declared value types. Existing templates generate cards. Duplicate entity IDs roll back the whole batch.",
+    tags: ["Notebase Rows"],
+  })
+    .errors(
+      pickPublicErrorMap(
+        "NOTEBASE_NOT_FOUND",
+        "CELL_VALIDATION_FAILED",
+        "CONCURRENT_POSITION_CONFLICT",
+        "NOTE_LIMIT_EXCEEDED",
+      ),
+    )
+    .errors(pickPublicErrorMap("RESOURCE_ALREADY_EXISTS"))
     .input(NotebaseRowCreateManyInputSchema)
     .output(NotebaseRowCreateManyOutputSchema),
 
-  update: notebaseProcedure
+  update: defineAgentProcedure({
+    method: "PATCH",
+    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.",
+    tags: ["Notebase Rows"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_ROW_NOT_FOUND", "CELL_VALIDATION_FAILED"))
-    .route({
-      method: "PATCH",
-      path: "/notebase-rows/{notebaseRowId}",
-      summary: "Update notebase row cells",
-      tags: ["Notebase Rows"],
-    })
+    .errors(pickPublicErrorMap("RESOURCE_UPDATE_CONFLICT"))
     .input(NotebaseRowUpdateInputSchema)
     .output(NotebaseRowUpdateOutputSchema),
 
-  delete: notebaseProcedure
+  delete: defineAgentProcedure({
+    method: "DELETE",
+    path: "/notebase-rows/{notebaseRowId}",
+    summary: "Delete note",
+    description:
+      "Permanently delete an owned note and its derived cards and review records. Return the deleted note ID.",
+    tags: ["Notebase Rows"],
+  })
     .errors(pickPublicErrorMap("NOTEBASE_ROW_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
-    .route({
-      method: "DELETE",
-      path: "/notebase-rows/{notebaseRowId}",
-      summary: "Delete notebase row",
-      tags: ["Notebase Rows"],
-    })
     .input(NotebaseRowDeleteInputSchema)
     .output(NotebaseRowDeleteOutputSchema),
 
-  reorder: notebaseProcedure
+  reorder: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
     .route({
       method: "POST",
@@ -78,4 +118,4 @@ export const notebaseRowContract = {
     })
     .input(NotebaseRowReorderInputSchema)
     .output(NotebaseRowReorderOutputSchema),
-}
+};