@read-frog/api-contract 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.24.0",
+  "version": "0.25.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.13.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/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/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

@@ -289,10 +289,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 +305,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/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/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(),
 });

package/src/schemas/web-sync.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+
+// What the web app reports about keeping its Electric data live. Every field is
+// an enum, so each label the API counts them under has a fixed set of values.
+
+/** The shapes the web app syncs, by their names in `@repo/electric-contract`. */
+export const webSyncShapeSchema = z.enum([
+  "notebases",
+  "notebaseColumns",
+  "notebaseRows",
+  "cardTemplates",
+  "cards",
+  "revlogs",
+  "mediaAssets",
+]);
+export type WebSyncShape = z.infer<typeof webSyncShapeSchema>;
+
+/** The write whose change the page waited to see come back over Electric. */
+export const webSyncOperationSchema = z.enum([
+  // The review session's own writes.
+  "review",
+  // A review the server had already recorded: it waits for that review's card
+  // and revlog, as its own transaction wrote nothing.
+  "reviewReplay",
+  "undo",
+  "bury",
+  "suspend",
+  "deleteNote",
+  // A synced collection's own mutation handlers.
+  "insert",
+  "update",
+  "delete",
+  // Other writes that wait for their change.
+  "setSleep",
+  "srsSettings",
+  "cardStatus",
+  "createTemplate",
+  "updateTemplate",
+]);
+export type WebSyncOperation = z.infer<typeof webSyncOperationSchema>;
+
+/** How the shape that lagged was receiving live changes. */
+export const webSyncTransportSchema = z.enum(["sse", "longPoll"]);
+export type WebSyncTransport = z.infer<typeof webSyncTransportSchema>;
+
+/**
+ * A write wait is only reported once its first wait ran out: `recovered` when
+ * reconnecting the lagging shapes brought the change, `failed` when the page
+ * gave up on it.
+ */
+export const webSyncWriteOutcomeSchema = z.enum(["recovered", "failed"]);
+export type WebSyncWriteOutcome = z.infer<typeof webSyncWriteOutcomeSchema>;
+
+export const webSyncStreamErrorTypeSchema = z.enum([
+  // 401: the session ended.
+  "unauthorized",
+  // 403: the notebase was deleted, or is someone else's.
+  "forbidden",
+  // 400 and any other 4xx.
+  "badRequest",
+  "clientError",
+  // A response without Electric's headers: a proxy or CORS in the way.
+  "missingHeaders",
+  // Anything that is not an HTTP status: an unreadable body, a parse error.
+  "unexpected",
+]);
+export type WebSyncStreamErrorType = z.infer<typeof webSyncStreamErrorTypeSchema>;
+
+/** `initial` before the shape first loaded, when the page shows the error at once. */
+export const webSyncStreamPhaseSchema = z.enum(["initial", "live"]);
+export type WebSyncStreamPhase = z.infer<typeof webSyncStreamPhaseSchema>;
+
+export const webSyncPageSchema = z.enum(["reviewCombined", "reviewNotebase"]);
+export type WebSyncPage = z.infer<typeof webSyncPageSchema>;
+
+export const webSyncUnavailableReasonSchema = z.enum([
+  // A write's change never came back, even after reconnecting.
+  "syncTimeout",
+  // A shape stream stopped.
+  "streamFailed",
+  // The notebase is gone: its shapes answer 403.
+  "notebaseGone",
+]);
+export type WebSyncUnavailableReason = z.infer<typeof webSyncUnavailableReasonSchema>;
+
+export const webSyncEventSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("writeWait"),
+      operation: webSyncOperationSchema,
+      outcome: webSyncWriteOutcomeSchema,
+      transport: webSyncTransportSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("streamError"),
+      shape: webSyncShapeSchema,
+      errorType: webSyncStreamErrorTypeSchema,
+      phase: webSyncStreamPhaseSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("unavailable"),
+      page: webSyncPageSchema,
+      reason: webSyncUnavailableReasonSchema,
+    })
+    .strict(),
+]);
+export type WebSyncEvent = z.infer<typeof webSyncEventSchema>;
+
+/** A page sends what happened within a second or so as one batch. */
+export const WEB_SYNC_REPORT_MAX_EVENTS = 20;
+
+export const reportWebSyncInputSchema = z
+  .object({
+    events: z.array(webSyncEventSchema).min(1).max(WEB_SYNC_REPORT_MAX_EVENTS),
+  })
+  .strict();
+export type ReportWebSyncInput = z.infer<typeof reportWebSyncInputSchema>;