@read-frog/api-contract 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -24,15 +24,15 @@
     }
   },
   "dependencies": {
-    "@orpc/contract": "^1.15.2",
-    "@read-frog/definitions": "0.11.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/billing.ts

@@ -14,6 +14,7 @@ const billingProcedure = oc.errors(
     "BILLING_CUSTOMER_NOT_FOUND",
     "BILLING_PASS_ACTIVE",
     "BILLING_CHANGE_SCHEDULED",
+    "BILLING_CHECKOUT_CONFLICT",
   ),
 );
 

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/hosted-ai.ts

@@ -1,6 +1,8 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { pickPublicErrorMap } from "#/public-errors";
 import {
+  HostedAiCreditPoolsInputSchema,
+  HostedAiCreditPoolsOutputSchema,
   HostedAiNoteSuggestionStreamInputSchema,
   HostedAiStatusInputSchema,
   HostedAiStatusOutputSchema,
@@ -15,6 +17,15 @@ const hostedAiStreamErrors = pickPublicErrorMap(
 );
 
 export const hostedAiContract = {
+  pools: oc
+    .route({
+      method: "GET",
+      path: "/hosted-ai/pools",
+      summary: "Get shared Built-in AI credit pools for a feature",
+      tags: ["Hosted AI"],
+    })
+    .input(HostedAiCreditPoolsInputSchema)
+    .output(HostedAiCreditPoolsOutputSchema),
   status: oc
     .route({
       method: "GET",

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-column.ts

@@ -44,7 +44,7 @@ export const notebaseColumnContract = {
     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.",
+      'Delete an owned field and remove its values from notes. Primary fields cannot be deleted, nor can a field a template references: one a columns face lists, or a layout face names as {{ ["<column id>"] }}. A layout that loops over ctx.fields, as the default dictionary template\'s back does to show every other filled field, references none of them, so those can be deleted and simply leave the card.',
     tags: ["Notebase Columns"],
   })
     .errors(

package/src/contracts/pdf-translation.ts

@@ -0,0 +1,140 @@
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
+import {
+  pdfTranslationDeleteOutputSchema,
+  pdfTranslationDownloadOutputSchema,
+  pdfTranslationGetOutputSchema,
+  pdfTranslationJobIdInputSchema,
+  pdfTranslationJobResourceSchema,
+  pdfTranslationListInputSchema,
+  pdfTranslationListOutputSchema,
+  pdfTranslationOutputInputSchema,
+  pdfTranslationPreviewOutputSchema,
+  pdfTranslationRequestUploadInputSchema,
+  pdfTranslationRequestUploadOutputSchema,
+  pdfTranslationStatusInputSchema,
+  pdfTranslationStatusOutputSchema,
+  pdfTranslationSubmitInputSchema,
+  pdfTranslationSubmitOutputSchema,
+} from "#/schemas/pdf-translation";
+
+const pdfTranslationProcedure = oc.errors(pickPublicErrorMap("PDF_TRANSLATION_UNAVAILABLE"));
+
+export const pdfTranslationContract = {
+  status: pdfTranslationProcedure
+    .route({
+      method: "GET",
+      path: "/pdf-translations/status",
+      summary: "How many free PDF translations the account has left",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationStatusInputSchema)
+    .output(pdfTranslationStatusOutputSchema),
+
+  list: pdfTranslationProcedure
+    .route({
+      method: "GET",
+      path: "/pdf-translations",
+      summary: "List recent PDF translations",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationListInputSchema)
+    .output(pdfTranslationListOutputSchema),
+
+  requestUpload: pdfTranslationProcedure
+    .errors(pickPublicErrorMap("PDF_TRANSLATION_FILE_TOO_LARGE"))
+    .route({
+      method: "POST",
+      path: "/pdf-translations/uploads",
+      summary: "Request a signed upload for a PDF to translate",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationRequestUploadInputSchema)
+    .output(pdfTranslationRequestUploadOutputSchema),
+
+  submit: pdfTranslationProcedure
+    .errors(
+      pickPublicErrorMap(
+        "HOSTED_AI_TIER_RESTRICTED",
+        "PDF_TRANSLATION_UPLOAD_NOT_FOUND",
+        "PDF_TRANSLATION_UPLOAD_EXPIRED",
+        "PDF_TRANSLATION_UPLOAD_NOT_COMPLETED",
+        "PDF_TRANSLATION_FILE_TOO_LARGE",
+        "PDF_TRANSLATION_INVALID_PDF",
+        "PDF_TRANSLATION_ALREADY_TRANSLATED",
+        "PDF_TRANSLATION_PAGE_LIMIT_EXCEEDED",
+        "PDF_TRANSLATION_QUEUE_FULL",
+        "PDF_TRANSLATION_IDEMPOTENCY_CONFLICT",
+        "PDF_TRANSLATION_INSUFFICIENT_CREDIT",
+      ),
+    )
+    .route({
+      method: "POST",
+      path: "/pdf-translations",
+      summary: "Translate uploaded PDFs",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationSubmitInputSchema)
+    .output(pdfTranslationSubmitOutputSchema),
+
+  get: pdfTranslationProcedure
+    .errors(pickPublicErrorMap("PDF_TRANSLATION_NOT_FOUND"))
+    .route({
+      method: "GET",
+      path: "/pdf-translations/{id}",
+      summary: "Get a PDF translation's status, with the others submitted with it",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationJobIdInputSchema)
+    .output(pdfTranslationGetOutputSchema),
+
+  cancel: pdfTranslationProcedure
+    .errors(pickPublicErrorMap("PDF_TRANSLATION_NOT_FOUND", "PDF_TRANSLATION_NOT_CANCELLABLE"))
+    .route({
+      method: "POST",
+      path: "/pdf-translations/{id}/cancel",
+      summary: "Cancel a PDF translation",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationJobIdInputSchema)
+    .output(pdfTranslationJobResourceSchema),
+
+  getPreviewUrl: pdfTranslationProcedure
+    .errors(pickPublicErrorMap("PDF_TRANSLATION_NOT_FOUND", "PDF_TRANSLATION_NOT_READY"))
+    .route({
+      method: "GET",
+      path: "/pdf-translations/{id}/preview-url",
+      summary: "Get a short-lived URL to read a translated PDF in the browser",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationOutputInputSchema)
+    .output(pdfTranslationPreviewOutputSchema),
+
+  getDownloadUrl: pdfTranslationProcedure
+    .errors(
+      pickPublicErrorMap(
+        "PDF_TRANSLATION_NOT_FOUND",
+        "PDF_TRANSLATION_NOT_READY",
+        "PDF_TRANSLATION_DOWNLOAD_RESTRICTED",
+      ),
+    )
+    .route({
+      method: "GET",
+      path: "/pdf-translations/{id}/download-url",
+      summary: "Get a download URL for a translated PDF",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationOutputInputSchema)
+    .output(pdfTranslationDownloadOutputSchema),
+
+  delete: pdfTranslationProcedure
+    .errors(pickPublicErrorMap("PDF_TRANSLATION_NOT_FOUND", "PDF_TRANSLATION_NOT_DELETABLE"))
+    .route({
+      method: "DELETE",
+      path: "/pdf-translations/{id}",
+      summary: "Delete a finished PDF translation and its files",
+      tags: ["PDF Translation"],
+    })
+    .input(pdfTranslationJobIdInputSchema)
+    .output(pdfTranslationDeleteOutputSchema),
+};

package/src/contracts/srs.ts

@@ -20,6 +20,10 @@ import {
   srsSetCardBuriedOutputSchema,
   srsSetCardSuspendedInputSchema,
   srsSetCardSuspendedOutputSchema,
+  srsApplyPostponeInputSchema,
+  srsApplyPostponeOutputSchema,
+  srsPreviewPostponeInputSchema,
+  srsPreviewPostponeOutputSchema,
 } from "#/schemas/srs";
 
 export const srsContract = {
@@ -141,4 +145,32 @@ export const srsContract = {
     )
     .input(srsSetCardSuspendedInputSchema)
     .output(srsSetCardSuspendedOutputSchema),
+
+  previewPostpone: oc
+    .errors(
+      pickPublicErrorMap(
+        "NOTEBASE_NOT_FOUND",
+        "RESCHEDULE_PREVIEW_TIMEOUT",
+        "RESCHEDULE_DAILY_LIMIT_INVALID",
+      ),
+    )
+    .route({
+      method: "POST",
+      path: "/srs/postpone/preview",
+      summary: "Preview postpone",
+      tags: ["SRS"],
+    })
+    .input(srsPreviewPostponeInputSchema)
+    .output(srsPreviewPostponeOutputSchema),
+
+  applyPostpone: oc
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND", "RESCHEDULE_PLAN_EXPIRED", "RESCHEDULE_STALE"))
+    .route({
+      method: "POST",
+      path: "/srs/postpone",
+      summary: "Apply postpone",
+      tags: ["SRS"],
+    })
+    .input(srsApplyPostponeInputSchema)
+    .output(srsApplyPostponeOutputSchema),
 };

package/src/contracts/stats.ts

@@ -1,6 +1,8 @@
+import { defineAgentProcedure } from "./shared";
 import { oc } from "@orpc/contract";
 import { pickPublicErrorMap } from "#/public-errors";
 import { notebaseRowGrowthStatsOutputSchema } from "#/schemas/notebase-stats";
+import { srsBacklogStatsInputSchema, srsBacklogStatsOutputSchema } from "#/schemas/srs";
 import { srsMemoryGrowthStatsOutputSchema } from "#/schemas/srs-stats";
 import { activityStatsOutputSchema, statsInputSchema } from "#/schemas/stats";
 
@@ -37,4 +39,18 @@ export const statsContract = {
     })
     .input(statsInputSchema)
     .output(notebaseRowGrowthStatsOutputSchema),
+
+  // A statistic like the rest, so reviews, which invalidate every `stats` query,
+  // mark it stale too.
+  backlogStats: defineAgentProcedure({
+    method: "GET",
+    path: "/srs/stats/backlog",
+    summary: "Get review backlogs",
+    description:
+      "Read overdue review backlogs for owned awake notebases in the supplied timezone. Only a notebase whose overdue reviews fill two or more days of its daily review limit is listed; the rest are left out. A notebase whose daily review limit is 0 or unlimited (-1) never returns anything, even when its ID is requested. Does not return note content or card faces.",
+    tags: ["Statistics"],
+  })
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .input(srsBacklogStatsInputSchema)
+    .output(srsBacklogStatsOutputSchema),
 };

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,12 +8,15 @@ 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";
+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";
 
@@ -27,12 +30,15 @@ export const contract = {
   hostedAi: hostedAiContract,
   masteryGoal: masteryGoalContract,
   mcpConnection: mcpConnectionContract,
+  media: mediaContract,
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
+  pdfTranslation: pdfTranslationContract,
   speech: speechContract,
   srs: srsContract,
   stats: statsContract,
+  telemetry: telemetryContract,
   user: userContract,
   videoTranscript: videoTranscriptContract,
 };
@@ -48,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";
@@ -55,6 +62,7 @@ export * from "./schemas/notebase-column";
 export * from "./schemas/notebase-row";
 export * from "./schemas/notebase-stats";
 export * from "./schemas/notebase-view";
+export * from "./schemas/pdf-translation";
 export * from "./schemas/speech";
 export * from "./schemas/srs";
 export * from "./schemas/srs-stats";
@@ -62,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

@@ -5,6 +5,10 @@ import {
   HostedAiModelTierSchema,
   HostedAiUpgradePlanSchema,
 } from "./schemas/hosted-ai";
+import {
+  PdfTranslationInsufficientCreditDataSchema,
+  PdfTranslationUploadErrorDataSchema,
+} from "./schemas/pdf-translation";
 
 interface PublicAppErrorDefinition {
   data?: z.ZodTypeAny;
@@ -216,6 +220,10 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "A subscription change is already scheduled",
     status: 409,
   },
+  BILLING_CHECKOUT_CONFLICT: {
+    message: "Please start a new checkout from the pricing page",
+    status: 409,
+  },
   CARD_NOT_REVIEWABLE: {
     message: "Card cannot be reviewed in its current state",
     status: 409,
@@ -248,6 +256,22 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Card status change is unavailable",
     status: 409,
   },
+  RESCHEDULE_PLAN_EXPIRED: {
+    message: "The reschedule plan has expired; preview it again",
+    status: 409,
+  },
+  RESCHEDULE_STALE: {
+    message: "Cards changed after the reschedule preview; preview it again",
+    status: 409,
+  },
+  RESCHEDULE_PREVIEW_TIMEOUT: {
+    message: "Planning the reschedule took too long",
+    status: 503,
+  },
+  RESCHEDULE_DAILY_LIMIT_INVALID: {
+    message: "The daily limit is outside the range a reschedule may suggest",
+    status: 422,
+  },
   NOTEBASE_VIEW_NOT_FOUND: {
     message: "Notebase view not found",
     status: 404,
@@ -265,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,
@@ -285,12 +305,114 @@ 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: {
     message: "This email link is not valid",
     status: 400,
   },
+  // The deployment has no worker to run translations (no Batch job
+  // definition or PDF bucket configured).
+  PDF_TRANSLATION_UNAVAILABLE: {
+    message: "PDF translation is not available right now",
+    status: 503,
+  },
+  PDF_TRANSLATION_NOT_FOUND: {
+    message: "PDF translation not found",
+    status: 404,
+  },
+  PDF_TRANSLATION_UPLOAD_NOT_FOUND: {
+    data: PdfTranslationUploadErrorDataSchema,
+    message: "PDF upload not found",
+    status: 404,
+  },
+  PDF_TRANSLATION_UPLOAD_EXPIRED: {
+    data: PdfTranslationUploadErrorDataSchema,
+    message: "The PDF upload has expired; upload the file again",
+    status: 410,
+  },
+  PDF_TRANSLATION_UPLOAD_NOT_COMPLETED: {
+    data: PdfTranslationUploadErrorDataSchema,
+    message: "The PDF upload has not been completed",
+    status: 409,
+  },
+  PDF_TRANSLATION_FILE_TOO_LARGE: {
+    message: "The PDF exceeds the maximum allowed size",
+    status: 413,
+  },
+  PDF_TRANSLATION_INVALID_PDF: {
+    data: PdfTranslationUploadErrorDataSchema,
+    message: "The file is not a readable PDF",
+    status: 422,
+  },
+  // Every PDF a translation delivers is marked as one, and none is translated
+  // again.
+  PDF_TRANSLATION_ALREADY_TRANSLATED: {
+    data: PdfTranslationUploadErrorDataSchema,
+    message: "This PDF is already a translation; upload the original instead",
+    status: 422,
+  },
+  PDF_TRANSLATION_PAGE_LIMIT_EXCEEDED: {
+    data: PdfTranslationUploadErrorDataSchema,
+    message: "The PDF has more pages than one translation allows",
+    status: 422,
+  },
+  // An account's unfinished translations run one at a time, and no more than
+  // PDF_TRANSLATION_MAX_BATCH_FILES of them wait at once.
+  PDF_TRANSLATION_QUEUE_FULL: {
+    message: "Too many PDF translations are waiting; try again when some have finished",
+    status: 409,
+  },
+  PDF_TRANSLATION_IDEMPOTENCY_CONFLICT: {
+    message: "This idempotency key was already used for a different PDF translation",
+    status: 409,
+  },
+  // The estimate is over what is left of the Built-in AI credit window.
+  // Running out midway stops the job instead (its error category is
+  // quota_exhausted).
+  PDF_TRANSLATION_INSUFFICIENT_CREDIT: {
+    data: PdfTranslationInsufficientCreditDataSchema,
+    message: "Not enough Built-in AI credit left to translate this PDF",
+    status: 429,
+  },
+  PDF_TRANSLATION_NOT_CANCELLABLE: {
+    message: "This PDF translation has already finished",
+    status: 409,
+  },
+  PDF_TRANSLATION_NOT_READY: {
+    message: "The translated PDF is not available",
+    status: 409,
+  },
+  // A Free account reads its one translation online; downloading it, as any
+  // translated PDF, needs a paid plan.
+  PDF_TRANSLATION_DOWNLOAD_RESTRICTED: {
+    message: "Downloading a translated PDF needs a Pro or Ultra plan",
+    status: 403,
+  },
+  PDF_TRANSLATION_NOT_DELETABLE: {
+    message: "Cancel this PDF translation before deleting it",
+    status: 409,
+  },
 } as const satisfies Record<string, PublicAppErrorDefinition>;
 
 export type PublicAppErrorCode = keyof typeof PUBLIC_APP_ERROR_DEFS;