@read-frog/api-contract 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   "dependencies": {
     "@orpc/contract": "^1.14.6",
     "zod": "^4.5.4",
-    "@read-frog/definitions": "0.5.0"
+    "@read-frog/definitions": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",

package/src/contracts/mcp-connection.ts

@@ -0,0 +1,26 @@
+import { oc } from "@orpc/contract";
+import {
+  mcpConnectionListOutputSchema,
+  mcpConnectionRevokeInputSchema,
+  mcpConnectionRevokeOutputSchema,
+} from "#/schemas/mcp-connection";
+
+export const mcpConnectionContract = {
+  list: oc
+    .route({
+      method: "GET",
+      path: "/mcp-connections",
+      summary: "List the OAuth clients the caller has authorized",
+      tags: ["MCP Connections"],
+    })
+    .output(mcpConnectionListOutputSchema),
+  revoke: oc
+    .route({
+      method: "POST",
+      path: "/mcp-connections/revoke",
+      summary: "Withdraw a client's authorization and revoke its tokens",
+      tags: ["MCP Connections"],
+    })
+    .input(mcpConnectionRevokeInputSchema)
+    .output(mcpConnectionRevokeOutputSchema),
+};

package/src/contracts/notebase-row.ts

@@ -13,10 +13,14 @@ import {
   NotebaseRowCreateManyOutputSchema,
   NotebaseRowCreateOutputSchema,
   NotebaseRowDeleteInputSchema,
+  NotebaseRowDeleteManyInputSchema,
+  NotebaseRowDeleteManyOutputSchema,
   NotebaseRowDeleteOutputSchema,
   NotebaseRowReorderInputSchema,
   NotebaseRowReorderOutputSchema,
   NotebaseRowUpdateInputSchema,
+  NotebaseRowUpdateManyInputSchema,
+  NotebaseRowUpdateManyOutputSchema,
   NotebaseRowUpdateOutputSchema,
 } from "#/schemas/notebase-row";
 
@@ -96,6 +100,21 @@ export const notebaseRowContract = {
     .input(NotebaseRowUpdateInputSchema)
     .output(NotebaseRowUpdateOutputSchema),
 
+  updateMany: defineAgentProcedure({
+    method: "PATCH",
+    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.",
+    tags: ["Notebase Rows"],
+  })
+    .errors(
+      pickPublicErrorMap("NOTEBASE_NOT_FOUND", "NOTEBASE_ROW_NOT_FOUND", "CELL_VALIDATION_FAILED"),
+    )
+    .errors(pickPublicErrorMap("RESOURCE_UPDATE_CONFLICT"))
+    .input(NotebaseRowUpdateManyInputSchema)
+    .output(NotebaseRowUpdateManyOutputSchema),
+
   delete: defineAgentProcedure({
     method: "DELETE",
     path: "/notebase-rows/{notebaseRowId}",
@@ -108,6 +127,18 @@ export const notebaseRowContract = {
     .input(NotebaseRowDeleteInputSchema)
     .output(NotebaseRowDeleteOutputSchema),
 
+  deleteMany: defineAgentProcedure({
+    method: "POST",
+    path: "/notebase-rows/batch/delete",
+    summary: "Delete notes",
+    description:
+      "Permanently delete 1–50 owned notes atomically, including their derived cards and review records. Notes may belong to different notebases. If any ID is missing or inaccessible, nothing is deleted. Return deleted IDs in input order.",
+    tags: ["Notebase Rows"],
+  })
+    .errors(pickPublicErrorMap("NOTEBASE_ROW_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
+    .input(NotebaseRowDeleteManyInputSchema)
+    .output(NotebaseRowDeleteManyOutputSchema),
+
   reorder: oc
     .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "CONCURRENT_POSITION_CONFLICT"))
     .route({

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 { mcpConnectionContract } from "./contracts/mcp-connection";
 import { notebaseContract } from "./contracts/notebase";
 import { notebaseColumnContract } from "./contracts/notebase-column";
 import { notebaseRowContract } from "./contracts/notebase-row";
@@ -20,6 +21,7 @@ export const contract = {
   cardTemplate: cardTemplateContract,
   ebook: ebookContract,
   hostedAi: hostedAiContract,
+  mcpConnection: mcpConnectionContract,
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
@@ -38,6 +40,7 @@ export * from "./schemas/billing";
 export * from "./schemas/card";
 export * from "./schemas/ebook";
 export * from "./schemas/hosted-ai";
+export * from "./schemas/mcp-connection";
 export * from "./schemas/notebase";
 export * from "./schemas/notebase-column";
 export * from "./schemas/notebase-row";

package/src/public-errors.ts

@@ -32,7 +32,7 @@ export const CellValidationFailedDataSchema = z
     notebaseColumnId: z.string(),
     details: CellValidationFailureDetailsSchema,
     reason: CellValidationFailureReasonSchema,
-    /** Index of the failing row within a batch input (createMany / initialRows). */
+    /** Index of the failing row within a batch input (createMany / updateMany / initialRows). */
     rowIndex: z.number().int().min(0).optional(),
   })
   .strict();

package/src/schemas/billing.ts

@@ -18,6 +18,32 @@ export type BillingSubscriptionStatus = z.infer<typeof billingSubscriptionStatus
 export const billingPlanSchema = z.enum(["free", "pro", "ultra"]);
 export type BillingPlan = z.infer<typeof billingPlanSchema>;
 
+/**
+ * Whether a plan may use a feature, given the plans that feature allows.
+ *
+ * An explicit set rather than a minimum tier: there is no rank table to keep in
+ * step with the plan enum, and any combination is expressible by writing it
+ * down. The cost is that nothing derives from it automatically -- a feature's
+ * pricing-card placement is a companion edit, noted at each `*_ALLOWED_PLANS`.
+ */
+export function isPlanAllowed(plan: BillingPlan, allowed: readonly BillingPlan[]): boolean {
+  return allowed.includes(plan);
+}
+
+/**
+ * Plans that may use the remote MCP server.
+ *
+ * Read by the server-side gate AND by the website's copy, so the page cannot
+ * promise access the API refuses. `satisfies` keeps the literal tuple type so
+ * the UI can render the plan names from this constant instead of hardcoding
+ * them.
+ *
+ * Companion edit when this changes: the feature bullet in
+ * `apps/www/src/routes/pricing.tsx` lives on the lowest allowed plan's card
+ * (higher cards inherit it through their "everything in <lower plan>" line).
+ */
+export const MCP_ALLOWED_PLANS = ["ultra"] as const satisfies readonly BillingPlan[];
+
 // 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/mcp-connection.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const mcpConnectionSchema = z
+  .object({
+    /** OAuth client identifier. For a CIMD client this is an https URL. */
+    clientId: z.string(),
+    /** The client's registered display name, absent when it never gave one. */
+    clientName: z.string().nullable(),
+    scopes: z.array(z.string()),
+    requestedUserInfoClaims: z.array(z.string()),
+    grantedAt: z.date().nullable(),
+    updatedAt: z.date().nullable(),
+    /**
+     * When this client last obtained an access token — the closest honest
+     * proxy for "last used" the OAuth tables record. A token is issued on
+     * connect and on every refresh, so an idle client's value stops advancing.
+     */
+    lastAuthorizedAt: z.date().nullable(),
+  })
+  .strict();
+export type McpConnection = z.infer<typeof mcpConnectionSchema>;
+
+export const mcpConnectionListOutputSchema = z.array(mcpConnectionSchema);
+
+export const mcpConnectionRevokeInputSchema = z.object({ clientId: z.string().min(1) }).strict();
+export type McpConnectionRevokeInput = z.infer<typeof mcpConnectionRevokeInputSchema>;
+
+export const mcpConnectionRevokeOutputSchema = z.object({ clientId: z.string() }).strict();

package/src/schemas/notebase-row.ts

@@ -94,6 +94,42 @@ export const NotebaseRowUpdateOutputSchema = z.object({
 });
 export type NotebaseRowUpdateOutput = z.infer<typeof NotebaseRowUpdateOutputSchema>;
 
+export const NOTEBASE_ROW_UPDATE_MANY_MAX_ROWS = 50;
+
+export const NotebaseRowUpdateManyInputSchema = z
+  .object({
+    notebaseId: z.uuid(),
+    rows: z
+      .array(
+        z.object({
+          id: z.uuid(),
+          data: notebaseRowUpdateDataSchema,
+        }),
+      )
+      .min(1)
+      .max(NOTEBASE_ROW_UPDATE_MANY_MAX_ROWS),
+  })
+  .superRefine((input, ctx) => {
+    const seenIds = new Set<string>();
+    input.rows.forEach((row, index) => {
+      if (seenIds.has(row.id)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `Duplicate row id "${row.id}".`,
+          path: ["rows", index, "id"],
+        });
+      }
+      seenIds.add(row.id);
+    });
+  });
+export type NotebaseRowUpdateManyInput = z.infer<typeof NotebaseRowUpdateManyInputSchema>;
+
+export const NotebaseRowUpdateManyOutputSchema = z.object({
+  items: z.array(notebaseRowSchema),
+  txid: z.number(),
+});
+export type NotebaseRowUpdateManyOutput = z.infer<typeof NotebaseRowUpdateManyOutputSchema>;
+
 export const NotebaseRowDeleteInputSchema = z.object({
   notebaseRowId: z.uuid(),
 });
@@ -102,6 +138,30 @@ export type NotebaseRowDeleteInput = z.infer<typeof NotebaseRowDeleteInputSchema
 export const NotebaseRowDeleteOutputSchema = deletionResultSchema;
 export type NotebaseRowDeleteOutput = z.infer<typeof NotebaseRowDeleteOutputSchema>;
 
+export const NOTEBASE_ROW_DELETE_MANY_MAX_ROWS = 50;
+
+export const NotebaseRowDeleteManyInputSchema = z
+  .object({
+    ids: z.array(z.uuid()).min(1).max(NOTEBASE_ROW_DELETE_MANY_MAX_ROWS),
+  })
+  .superRefine((input, ctx) => {
+    const seenIds = new Set<string>();
+    input.ids.forEach((id, index) => {
+      if (seenIds.has(id)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `Duplicate row id "${id}".`,
+          path: ["ids", index],
+        });
+      }
+      seenIds.add(id);
+    });
+  });
+export type NotebaseRowDeleteManyInput = z.infer<typeof NotebaseRowDeleteManyInputSchema>;
+
+export const NotebaseRowDeleteManyOutputSchema = z.object({ ids: z.array(z.uuid()) });
+export type NotebaseRowDeleteManyOutput = z.infer<typeof NotebaseRowDeleteManyOutputSchema>;
+
 export const NotebaseRowReorderInputSchema = z.object({
   notebaseId: z.uuid(),
   ids: z.array(z.uuid()),