@read-frog/api-contract 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@read-frog/api-contract",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@orpc/contract": "^1.15.2",
-    "@read-frog/definitions": "0.11.0",
+    "@read-frog/definitions": "0.12.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

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/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/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/index.ts

@@ -11,6 +11,7 @@ import { mcpConnectionContract } from "./contracts/mcp-connection";
 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";
@@ -30,6 +31,7 @@ export const contract = {
   notebase: notebaseContract,
   notebaseColumn: notebaseColumnContract,
   notebaseRow: notebaseRowContract,
+  pdfTranslation: pdfTranslationContract,
   speech: speechContract,
   srs: srsContract,
   stats: statsContract,
@@ -55,6 +57,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";

package/src/public-errors.ts

@@ -1,6 +1,14 @@
 import type { ErrorMap } from "@orpc/contract";
 import { z } from "zod";
-import { HostedAiCreditPolicyIdSchema, HostedAiModelTierSchema } from "./schemas/hosted-ai";
+import {
+  HostedAiCreditPolicyIdSchema,
+  HostedAiModelTierSchema,
+  HostedAiUpgradePlanSchema,
+} from "./schemas/hosted-ai";
+import {
+  PdfTranslationInsufficientCreditDataSchema,
+  PdfTranslationUploadErrorDataSchema,
+} from "./schemas/pdf-translation";
 
 interface PublicAppErrorDefinition {
   data?: z.ZodTypeAny;
@@ -74,6 +82,8 @@ export type CardTemplateNotebaseColumnInUseData = z.infer<
 
 export const HostedAiTierRestrictedDataSchema = z.strictObject({
   modelTier: HostedAiModelTierSchema,
+  /** The cheapest plan that unlocks it; a client offers "Pro or Ultra" for `pro`. */
+  upgradeTo: HostedAiUpgradePlanSchema,
 });
 
 export const HostedAiQuotaExhaustedDataSchema = z.strictObject({
@@ -210,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,
@@ -242,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,
@@ -285,6 +315,88 @@ export const PUBLIC_APP_ERROR_DEFS = {
     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;

package/src/schemas/billing.ts

@@ -1,5 +1,6 @@
 import type { AppLocale } from "./app-locale";
 import { z } from "zod";
+import { checkoutAttributionInputSchema } from "@read-frog/definitions";
 import { appLocaleSchema } from "./app-locale";
 
 export const billingIntervalSchema = z.enum(["month", "year"]);
@@ -116,6 +117,8 @@ export const billingCreateCheckoutSessionInputSchema = z
     interval: billingIntervalSchema,
     locale: appLocaleSchema,
     plan: billingCheckoutPlanSchema.default("pro"),
+    requestId: z.uuid().optional(),
+    attribution: checkoutAttributionInputSchema.optional(),
   })
   .strict();
 export type BillingCreateCheckoutSessionInput = z.infer<

package/src/schemas/email-preferences.ts

@@ -34,11 +34,52 @@ export const emailCategoryStateSchema = z
   .strict();
 export type EmailCategoryState = z.infer<typeof emailCategoryStateSchema>;
 
+/**
+ * The category whose emails a person can time: Practice reminders, seeded as
+ * `practice` (packages/db's migration 0067). The settings page shows the
+ * time under its switch.
+ */
+export const PRACTICE_REMINDER_CATEGORY_KEY = "practice";
+
+/**
+ * When practice reminders reach someone who never chose a time: 18:00 in
+ * their own time zone. The page shows it as the choice until one is made;
+ * Ribbit's reminder automation sets the same as its own time, for people
+ * without one (docs/ribbit/phase-3-automations.md).
+ */
+export const PRACTICE_REMINDER_DEFAULT_TIME = "18:00";
+
+/** A time of day on the hour, `HH:00`: Ribbit takes people into a schedule once an hour. */
+export const practiceReminderTimeSchema = z
+  .string()
+  .regex(/^([01]\d|2[0-3]):00$/, "Choose a time on the hour.");
+export type PracticeReminderTime = z.infer<typeof practiceReminderTimeSchema>;
+
+/** The times the page offers: every hour of the day. */
+export const PRACTICE_REMINDER_TIMES: readonly PracticeReminderTime[] = Array.from(
+  { length: 24 },
+  (_, hour) => `${String(hour).padStart(2, "0")}:00`,
+);
+
+/**
+ * The reminders area of `user_preferences`, as the database holds it: what
+ * is not there, or no longer reads, is the default. `practiceTime` is the
+ * practice reminder's time of day, in the person's own zone; null until they
+ * choose one.
+ */
+export const remindersPreferencesSchema = z.object({
+  practiceTime: practiceReminderTimeSchema.nullable().catch(null).default(null),
+});
+export type RemindersPreferences = z.infer<typeof remindersPreferencesSchema>;
+
 export const emailPreferencesStateSchema = z
   .object({
     // In display order; archived categories are left out.
     categories: z.array(emailCategoryStateSchema),
     unsubscribedAll: z.boolean(),
+    // When practice reminders reach them, in their own time zone; null while
+    // they never chose one (the page then shows PRACTICE_REMINDER_DEFAULT_TIME).
+    practiceReminderTime: practiceReminderTimeSchema.nullable(),
   })
   .strict();
 export type EmailPreferencesState = z.infer<typeof emailPreferencesStateSchema>;
@@ -68,6 +109,9 @@ const emailPreferencesChangesShape = {
   // categories added later; false ends that and leaves each category as it was
   // before.
   unsubscribedAll: z.boolean().optional(),
+  // Sets when practice reminders reach them (null: back to the default); left
+  // out, it stays as it is.
+  practiceReminderTime: practiceReminderTimeSchema.nullable().optional(),
 };
 
 export const emailPreferencesGetInputSchema = z

package/src/schemas/hosted-ai.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { billingPlanSchema } from "./billing";
 
 export const HostedAiOutputFieldTypeSchema = z.enum(["string", "number"]);
 
@@ -31,6 +32,9 @@ export const HostedAiFeatureSchema = z.enum([
   "videoSubtitles",
   "inputTranslation",
   "languageDetection",
+  // Charged by the PDF worker's proxy, not called by clients; `status`
+  // leaves it out (see the router's HOSTED_AI_FEATURES).
+  "pdfTranslation",
 ]);
 export const HostedAiRequestIdSchema = z.uuid();
 
@@ -159,18 +163,36 @@ export const HOSTED_AI_CLIENT_STREAM_PART_TYPES = [
  */
 export const HostedAiStatusInputSchema = z.object({});
 
+/**
+ * `pro_required` means the Pro plan or any plan above it; `ultra_required`
+ * means Ultra. Appended last, so a client that predates a value falls back on
+ * its own default instead of misreading it.
+ */
 export const HostedAiUnavailableReasonSchema = z.enum([
   "authentication_required",
   "ultra_required",
   "quota_exhausted",
   "service_unavailable",
+  "pro_required",
 ]);
 
+/**
+ * The cheapest plan an account would need to buy for something it cannot use
+ * now. Any plan above it works too, so `pro` reads as "Pro or Ultra".
+ */
+export const HostedAiUpgradePlanSchema = billingPlanSchema.exclude(["free"]);
+
 export const HostedAiCreditPolicyIdSchema = z.enum([
   "custom-action-guest-daily-v1",
   "custom-action-user-daily-v1",
+  // Retired: Pro draws on a weekly pool now. Kept because the database still
+  // holds pools under it.
   "custom-action-pro-daily-v1",
   "ultra-weekly-v1",
+  // Retired: Pro's weekly pool in UTC calendar weeks. Kept for the same reason.
+  "pro-weekly-v1",
+  // Pro's weekly pool, in weeks that run from when the plan started, as Ultra's do.
+  "pro-weekly-v2",
 ]);
 
 export const HostedAiCreditPeriodKindSchema = z.enum(["daily", "weekly"]);
@@ -241,15 +263,29 @@ export const HostedAiCreditPoolStatusSchema = z.discriminatedUnion("periodKind",
   HostedAiOneTimeCreditStatusSchema,
 ]);
 
+/** Feature-scoped credit display, separate from the legacy extension status shape. */
+export const HostedAiCreditPoolsInputSchema = z.strictObject({ feature: HostedAiFeatureSchema });
+export const HostedAiCreditPoolsOutputSchema = z.strictObject({
+  pools: z.array(HostedAiCreditPoolStatusSchema),
+});
+
 export const HostedAiTierStatusSchema = z.strictObject({
   accessAllowed: z.boolean(),
   available: z.boolean(),
   unavailableReason: HostedAiUnavailableReasonSchema.nullable(),
   /**
-   * Viewer-independent product fact: no non-Ultra account can ever use this
-   * feature/tier, so signing in alone will not unlock it. Unlike the fields
-   * above, this does not vary with the caller's identity or plan — clients use
-   * it to label Ultra-only options rather than to gate the current user.
+   * The cheapest plan this account would need to use the tier, or null when it
+   * needs none: its plan or a one-time pool already covers it, or the tier is
+   * open to every signed-in account. For a guest it is the plan needed after
+   * signing in. Clients badge an option with it and offer that plan.
+   */
+  upgradeTo: HostedAiUpgradePlanSchema.nullable(),
+  /**
+   * @deprecated Read `upgradeTo`. Viewer-independent product fact: no
+   * non-Ultra account can ever use this feature/tier. Extensions released
+   * before `upgradeTo` badge options with it, including for Ultra accounts.
+   *
+   * TODO(2026-11-21): remove once those extensions have drained (#710).
    */
   requiresUltra: z.boolean(),
   modelRevision: z.string().trim().min(1),
@@ -302,6 +338,7 @@ export type HostedAiNoteSuggestionObject = z.infer<typeof HostedAiNoteSuggestion
 export type HostedAiStreamPart = z.infer<typeof HostedAiStreamPartSchema>;
 export type HostedAiStatusInput = z.infer<typeof HostedAiStatusInputSchema>;
 export type HostedAiUnavailableReason = z.infer<typeof HostedAiUnavailableReasonSchema>;
+export type HostedAiUpgradePlan = z.infer<typeof HostedAiUpgradePlanSchema>;
 export type HostedAiCreditPolicyId = z.infer<typeof HostedAiCreditPolicyIdSchema>;
 export type HostedAiCreditPeriodKind = z.infer<typeof HostedAiCreditPeriodKindSchema>;
 export type HostedAiQuotaScope = z.infer<typeof HostedAiQuotaScopeSchema>;

package/src/schemas/notebase.ts

@@ -3,6 +3,7 @@ import {
   notebaseColumnConfigSchema,
   schedulingParamsShape,
   srsModelVersionSchema,
+  srsSleepSourceSchema,
   srsWeightsSchema,
 } from "@read-frog/definitions";
 import { z } from "zod";
@@ -43,6 +44,8 @@ export const notebaseSchema = z.object({
   srsModelVersion: srsModelVersionSchema,
   // Null = awake; set = excluded from the combined review. Written by notebase.setSleep and auto sleep.
   srsSleepingAt: z.date().nullable(),
+  // Who put it to sleep; null exactly when awake.
+  srsSleepSource: srsSleepSourceSchema.nullable(),
   createdAt: z.date(),
   updatedAt: z.date(),
 });