@read-frog/api-contract 0.21.1 → 0.22.0

package/package.json

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

package/src/contracts/ebook.ts

@@ -45,7 +45,9 @@ export const ebookContract = {
     .output(ebookGetOutputSchema),
 
   requestUpload: ebookProcedure
-    .errors(pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_LIMIT_EXCEEDED"))
+    .errors(
+      pickPublicErrorMap("EBOOK_BETA_RESTRICTED", "EBOOK_LIMIT_EXCEEDED", "EBOOK_FILE_TOO_LARGE"),
+    )
     .route({
       method: "POST",
       path: "/ebooks/uploads",

package/src/contracts/email-preferences.ts

@@ -0,0 +1,55 @@
+import { oc } from "@orpc/contract";
+import { pickPublicErrorMap } from "#/public-errors";
+import {
+  emailPreferencesByTokenStateSchema,
+  emailPreferencesGetByTokenInputSchema,
+  emailPreferencesGetInputSchema,
+  emailPreferencesStateSchema,
+  emailPreferencesUpdateByTokenInputSchema,
+  emailPreferencesUpdateInputSchema,
+} from "#/schemas/email-preferences";
+
+// Every write returns the whole state, so a client can update optimistically
+// and then take the server's answer.
+export const emailPreferencesContract = {
+  get: oc
+    .route({
+      method: "GET",
+      path: "/users/me/email-preferences",
+      summary: "Get which emails the authenticated user receives",
+      tags: ["Email preferences"],
+    })
+    .input(emailPreferencesGetInputSchema)
+    .output(emailPreferencesStateSchema),
+  update: oc
+    .route({
+      method: "PATCH",
+      path: "/users/me/email-preferences",
+      summary: "Change which emails the authenticated user receives",
+      tags: ["Email preferences"],
+    })
+    .input(emailPreferencesUpdateInputSchema)
+    .output(emailPreferencesStateSchema),
+  // Public: the token in an email's link stands in for signing in. POST keeps
+  // the token out of URLs and logs.
+  getByToken: oc
+    .route({
+      method: "POST",
+      path: "/email-preferences/by-token",
+      summary: "Get the email preferences an email link is for",
+      tags: ["Email preferences"],
+    })
+    .errors(pickPublicErrorMap("EMAIL_LINK_INVALID"))
+    .input(emailPreferencesGetByTokenInputSchema)
+    .output(emailPreferencesByTokenStateSchema),
+  updateByToken: oc
+    .route({
+      method: "POST",
+      path: "/email-preferences/by-token/update",
+      summary: "Change the email preferences an email link is for",
+      tags: ["Email preferences"],
+    })
+    .errors(pickPublicErrorMap("EMAIL_LINK_INVALID"))
+    .input(emailPreferencesUpdateByTokenInputSchema)
+    .output(emailPreferencesByTokenStateSchema),
+};

package/src/contracts/feature-access.ts

@@ -0,0 +1,17 @@
+import { oc } from "@orpc/contract";
+import {
+  FeatureAccessStatusInputSchema,
+  FeatureAccessStatusOutputSchema,
+} from "#/schemas/feature-access";
+
+export const featureAccessContract = {
+  status: oc
+    .route({
+      method: "GET",
+      path: "/feature-access/status",
+      summary: "Get whether the caller can use a gated feature",
+      tags: ["Feature Access"],
+    })
+    .input(FeatureAccessStatusInputSchema)
+    .output(FeatureAccessStatusOutputSchema),
+};

package/src/contracts/notebase.ts

@@ -13,6 +13,8 @@ import {
   NotebaseGetSummaryOutputSchema,
   NotebaseListInputSchema,
   NotebaseListOutputSchema,
+  NotebaseSetSleepInputSchema,
+  NotebaseSetSleepOutputSchema,
   NotebaseUpdateInputSchema,
   NotebaseUpdateOutputSchema,
 } from "#/schemas/notebase";
@@ -89,6 +91,18 @@ export const notebaseContract = {
     .input(NotebaseUpdateInputSchema)
     .output(NotebaseUpdateOutputSchema),
 
+  setSleep: defineAgentProcedure({
+    method: "POST",
+    path: "/notebases/{id}/sleep",
+    summary: "Set notebase sleep",
+    description:
+      "Put an owned notebase to sleep (enabled=true) or wake it (enabled=false). A sleeping notebase is left out of the combined review; its cards, memory states and review history are unchanged and it can still be reviewed directly. A request matching the current state succeeds without a change.",
+    tags: ["Notebases"],
+  })
+    .errors(pickPublicErrorMap("NOTEBASE_NOT_FOUND"))
+    .input(NotebaseSetSleepInputSchema)
+    .output(NotebaseSetSleepOutputSchema),
+
   delete: defineAgentProcedure({
     method: "DELETE",
     path: "/notebases/{id}",

package/src/contracts/speech.ts

@@ -37,7 +37,7 @@ export const speechContract = {
     .route({
       method: "POST",
       path: "/speech/synthesize",
-      summary: "Read a text aloud, as MP3 audio",
+      summary: "Read a text aloud, and link to its MP3 audio",
       tags: ["Speech"],
     })
     .input(speechSynthesizeInputSchema)

package/src/contracts/user.ts

@@ -1,7 +1,11 @@
 import { oc } from "@orpc/contract";
 import {
+  userEnsureLocaleInputSchema,
+  userEnsureLocaleOutputSchema,
   userEnsureTimezoneInputSchema,
   userEnsureTimezoneOutputSchema,
+  userUpdateLocaleInputSchema,
+  userUpdateLocaleOutputSchema,
   userUpdateTimezoneInputSchema,
   userUpdateTimezoneOutputSchema,
 } from "#/schemas/user";
@@ -25,4 +29,22 @@ export const userContract = {
     })
     .input(userUpdateTimezoneInputSchema)
     .output(userUpdateTimezoneOutputSchema),
+  ensureLocale: oc
+    .route({
+      method: "POST",
+      path: "/users/me/locale/ensure",
+      summary: "Ensure the authenticated user has a locale",
+      tags: ["Users"],
+    })
+    .input(userEnsureLocaleInputSchema)
+    .output(userEnsureLocaleOutputSchema),
+  updateLocale: oc
+    .route({
+      method: "PATCH",
+      path: "/users/me/locale",
+      summary: "Update the authenticated user's locale",
+      tags: ["Users"],
+    })
+    .input(userUpdateLocaleInputSchema)
+    .output(userUpdateLocaleOutputSchema),
 };

package/src/index.ts

@@ -1,9 +1,10 @@
 import type { ContractRouterClient } from "@orpc/contract";
-import { betaAccessContract } from "./contracts/beta-access";
 import { billingContract } from "./contracts/billing";
 import { cardContract } from "./contracts/card";
 import { cardTemplateContract } from "./contracts/card-template";
 import { ebookContract } from "./contracts/ebook";
+import { emailPreferencesContract } from "./contracts/email-preferences";
+import { featureAccessContract } from "./contracts/feature-access";
 import { hostedAiContract } from "./contracts/hosted-ai";
 import { masteryGoalContract } from "./contracts/mastery-goal";
 import { mcpConnectionContract } from "./contracts/mcp-connection";
@@ -17,11 +18,12 @@ import { userContract } from "./contracts/user";
 import { videoTranscriptContract } from "./contracts/video-transcript";
 
 export const contract = {
-  betaAccess: betaAccessContract,
   billing: billingContract,
   card: cardContract,
   cardTemplate: cardTemplateContract,
   ebook: ebookContract,
+  emailPreferences: emailPreferencesContract,
+  featureAccess: featureAccessContract,
   hostedAi: hostedAiContract,
   masteryGoal: masteryGoalContract,
   mcpConnection: mcpConnectionContract,
@@ -39,10 +41,12 @@ export type ORPCRouterClient = ContractRouterClient<typeof contract>;
 
 export { type AgentRoute, defineAgentProcedure } from "./contracts/shared";
 export * from "./public-errors";
-export * from "./schemas/beta-access";
+export * from "./schemas/app-locale";
 export * from "./schemas/billing";
 export * from "./schemas/card";
 export * from "./schemas/ebook";
+export * from "./schemas/email-preferences";
+export * from "./schemas/feature-access";
 export * from "./schemas/hosted-ai";
 export * from "./schemas/mastery-goal";
 export * from "./schemas/mcp-connection";

package/src/public-errors.ts

@@ -112,21 +112,10 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Built-in AI credit exhausted",
     status: 429,
   },
-  NOTEBASE_BETA_RESTRICTED: {
-    message: "Notebase is currently in beta for selected accounts",
-    status: 403,
-  },
   NOTEBASE_NOT_FOUND: {
     message: "Notebase not found",
     status: 404,
   },
-  // Retired at launch (2026-08-14) but kept defined for one release so old
-  // clients' error maps keep parsing; the server no longer emits it. Remove
-  // together with the beta feature key in the follow-up cleanup.
-  VIDEO_TRANSCRIPTION_BETA_RESTRICTED: {
-    message: "Video transcription is currently in beta for selected accounts",
-    status: 403,
-  },
   VIDEO_TRANSCRIPTION_SUBSCRIPTION_REQUIRED: {
     message: "AI subtitles require a Pro or Ultra subscription",
     status: 403,
@@ -290,6 +279,12 @@ export const PUBLIC_APP_ERROR_DEFS = {
     message: "Ebook 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,
+  },
 } as const satisfies Record<string, PublicAppErrorDefinition>;
 
 export type PublicAppErrorCode = keyof typeof PUBLIC_APP_ERROR_DEFS;

package/src/schemas/app-locale.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+/**
+ * The languages the website is in (`project.inlang/settings.json`; a test in
+ * apps/www keeps the two in step). Used wherever the server writes for a
+ * person: Stripe pages, emails, and the account's `locale`.
+ */
+export const appLocaleSchema = z.enum(["en", "es", "ja", "ko", "ru", "tr", "vi", "zh", "zh-TW"]);
+export type AppLocale = z.infer<typeof appLocaleSchema>;

package/src/schemas/billing.ts

@@ -1,4 +1,6 @@
+import type { AppLocale } from "./app-locale";
 import { z } from "zod";
+import { appLocaleSchema } from "./app-locale";
 
 export const billingIntervalSchema = z.enum(["month", "year"]);
 export type BillingInterval = z.infer<typeof billingIntervalSchema>;
@@ -19,30 +21,20 @@ 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.
+ * How many MCP tool calls each plan may make in a day (24 hours from the first
+ * one); `null` is no limit. Each `tools/call` counts once, whatever the tool.
  *
- * 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 MCP server's gate AND by the website's copy, so the pages cannot
+ * promise calls the server refuses.
  *
- * 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).
+ * Companion edit when this changes: the MCP docs under
+ * `apps/www/content/docs/mcp/` and `account-and-plans`, which state the numbers.
  */
-export const MCP_ALLOWED_PLANS = ["ultra"] as const satisfies readonly BillingPlan[];
+export const MCP_DAILY_CALL_LIMITS = {
+  free: 10,
+  pro: 50,
+  ultra: null,
+} as const satisfies Record<BillingPlan, number | null>;
 
 // Plans a user can actively check out into (the free tier has no price).
 export const billingCheckoutPlanSchema = z.enum(["pro", "ultra"]);
@@ -51,18 +43,10 @@ export type BillingCheckoutPlan = z.infer<typeof billingCheckoutPlanSchema>;
 export const billingCurrencySchema = z.enum(["usd", "cad", "cny"]);
 export type BillingCurrency = z.infer<typeof billingCurrencySchema>;
 
-export const billingLocaleSchema = z.enum([
-  "en",
-  "es",
-  "ja",
-  "ko",
-  "ru",
-  "tr",
-  "vi",
-  "zh",
-  "zh-TW",
-]);
-export type BillingLocale = z.infer<typeof billingLocaleSchema>;
+// The billing name of `appLocaleSchema`, which it was before the account had a
+// locale of its own; kept so existing imports keep working.
+export const billingLocaleSchema = appLocaleSchema;
+export type BillingLocale = AppLocale;
 
 export const billingAccessSourceSchema = z.enum(["subscription", "pass"]);
 export type BillingAccessSource = z.infer<typeof billingAccessSourceSchema>;
@@ -76,6 +60,33 @@ export const billingScheduledChangeSchema = z
   .strict();
 export type BillingScheduledChange = z.infer<typeof billingScheduledChangeSchema>;
 
+/**
+ * The zone a payment deadline is shown in, as a date with no time. UTC−12 is
+ * the last zone to finish a day, and `dueBy` is the end of a day there, so the
+ * date it shows stays open in every customer's zone until their own midnight.
+ */
+export const BILLING_PAYMENT_DUE_TIME_ZONE = "Etc/GMT+12";
+
+/**
+ * A renewal whose payment failed. The plan stays until `dueBy`; paying the
+ * invoice before then (or later, until the subscription is canceled) restores
+ * the subscription as if the payment had gone through.
+ */
+export const billingPaymentDueSchema = z
+  .object({
+    /** The last instant of the plan; show it in BILLING_PAYMENT_DUE_TIME_ZONE. */
+    dueBy: z.coerce.date(),
+    /**
+     * The plan the payment keeps. Not `BillingStatus.plan`: past `dueBy` that
+     * already reads "free" while the invoice is still payable.
+     */
+    plan: billingCheckoutPlanSchema,
+    /** The Stripe-hosted page that pays the invoice; null if Stripe gave none. */
+    url: z.url().nullable(),
+  })
+  .strict();
+export type BillingPaymentDue = z.infer<typeof billingPaymentDueSchema>;
+
 export const billingStatusSchema = z
   .object({
     plan: billingPlanSchema,
@@ -91,6 +102,7 @@ export const billingStatusSchema = z
     cancelAt: z.coerce.date().nullable(),
     accessSource: billingAccessSourceSchema.nullable(),
     scheduledChange: billingScheduledChangeSchema.nullable(),
+    paymentDue: billingPaymentDueSchema.nullable(),
     unlimitedNotebaseNotes: z.boolean(),
     notebaseNoteLimit: z.number().int().positive(),
     notebaseNoteCount: z.number().int().min(0),
@@ -102,7 +114,7 @@ export const billingCreateCheckoutSessionInputSchema = z
   .object({
     currency: billingCurrencySchema,
     interval: billingIntervalSchema,
-    locale: billingLocaleSchema,
+    locale: appLocaleSchema,
     plan: billingCheckoutPlanSchema.default("pro"),
   })
   .strict();
@@ -112,7 +124,7 @@ export type BillingCreateCheckoutSessionInput = z.infer<
 
 export const billingCreateCustomerPortalSessionInputSchema = z
   .object({
-    locale: billingLocaleSchema,
+    locale: appLocaleSchema,
   })
   .strict();
 export type BillingCreateCustomerPortalSessionInput = z.infer<

package/src/schemas/ebook.ts

@@ -68,28 +68,36 @@ export const ebookRequestUploadInputSchema = z
     title: z.string().min(1).max(500),
     author: z.string().max(500).optional(),
     language: z.string().max(35).optional(),
-    coverContentType: ebookCoverContentTypeSchema.optional(),
+    // Exact sizes: each upload is signed for them, and storage refuses any other file.
+    fileByteSize: z.number().int().min(1),
+    cover: z
+      .object({
+        contentType: ebookCoverContentTypeSchema,
+        byteSize: z.number().int().min(1),
+      })
+      .strict()
+      .optional(),
   })
   .strict();
 export type EbookRequestUploadInput = z.infer<typeof ebookRequestUploadInputSchema>;
 
 /**
- * S3 POST form policy. `fields` must be appended to the form in iteration order
- * with the file last; S3 ignores anything sent after the `file` part.
+ * A signed PUT: send the file to `url` with exactly `headers`. The signature
+ * covers the file's type and exact size, so storage refuses any other file.
  */
-export const ebookPresignedPostSchema = z
+export const ebookPresignedUploadSchema = z
   .object({
     url: z.url(),
-    fields: z.record(z.string(), z.string()),
+    headers: z.record(z.string(), z.string()),
   })
   .strict();
-export type EbookPresignedPost = z.infer<typeof ebookPresignedPostSchema>;
+export type EbookPresignedUpload = z.infer<typeof ebookPresignedUploadSchema>;
 
 export const ebookRequestUploadOutputSchema = z
   .object({
     ebookId: z.uuid(),
-    upload: ebookPresignedPostSchema,
-    coverUpload: ebookPresignedPostSchema.nullable(),
+    upload: ebookPresignedUploadSchema,
+    coverUpload: ebookPresignedUploadSchema.nullable(),
     expiresAt: z.coerce.date(),
   })
   .strict();

package/src/schemas/email-preferences.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { appLocaleSchema } from "./app-locale";
+
+// Which marketing and lifecycle emails a user gets, by category. Read and
+// changed signed in (the settings page), or through the signed token in an
+// email's unsubscribe link (the unsubscribe page that link opens, which needs
+// no sign-in). Category names come from the server in the requested locale.
+
+/** A category's key, such as `promotions`. */
+export const emailCategoryKeySchema = z
+  .string()
+  .max(64)
+  .regex(/^[a-z][a-z0-9_]*$/);
+export type EmailCategoryKey = z.infer<typeof emailCategoryKeySchema>;
+
+/** The token in an email's unsubscribe link. */
+export const emailLinkTokenSchema = z.string().min(1).max(1024);
+
+export const emailCategoryStateSchema = z
+  .object({
+    key: z.string(),
+    // In the requested locale, or English when the category has none for it.
+    name: z.string(),
+    description: z.string().nullable(),
+    // Promotional mail.
+    commercial: z.boolean(),
+    // Notices about the account and the service, which nobody can unsubscribe
+    // from: always subscribed, "unsubscribe from all" included, and a change
+    // to it is ignored. Show it on, without a way to turn it off.
+    required: z.boolean(),
+    // Whether the user gets this category now, "unsubscribe from all" included.
+    subscribed: z.boolean(),
+  })
+  .strict();
+export type EmailCategoryState = z.infer<typeof emailCategoryStateSchema>;
+
+export const emailPreferencesStateSchema = z
+  .object({
+    // In display order; archived categories are left out.
+    categories: z.array(emailCategoryStateSchema),
+    unsubscribedAll: z.boolean(),
+  })
+  .strict();
+export type EmailPreferencesState = z.infer<typeof emailPreferencesStateSchema>;
+
+/**
+ * What the page a link opens shows on top of the state: whose preferences they
+ * are, without the full address, and the category the link was for, if any.
+ */
+export const emailPreferencesByTokenStateSchema = z
+  .object({
+    ...emailPreferencesStateSchema.shape,
+    maskedEmail: z.string(),
+    // The link's category, when it is one the user can unsubscribe from: null
+    // for a link without one, or for an archived, required or unknown one.
+    highlightCategory: z.string().nullable(),
+  })
+  .strict();
+export type EmailPreferencesByTokenState = z.infer<typeof emailPreferencesByTokenStateSchema>;
+
+const emailPreferencesChangesShape = {
+  // Subscribes (true) or unsubscribes (false) the categories it names, and
+  // leaves the rest alone. Subscribing to one after "unsubscribe from all"
+  // ends it, and every other category stays unsubscribed. A required category
+  // is ignored.
+  categories: z.record(emailCategoryKeySchema, z.boolean()).optional(),
+  // true unsubscribes from every category but the required ones, including
+  // categories added later; false ends that and leaves each category as it was
+  // before.
+  unsubscribedAll: z.boolean().optional(),
+};
+
+export const emailPreferencesGetInputSchema = z
+  .object({
+    locale: appLocaleSchema,
+  })
+  .strict();
+export type EmailPreferencesGetInput = z.infer<typeof emailPreferencesGetInputSchema>;
+
+export const emailPreferencesUpdateInputSchema = z
+  .object({
+    locale: appLocaleSchema,
+    ...emailPreferencesChangesShape,
+  })
+  .strict();
+export type EmailPreferencesUpdateInput = z.infer<typeof emailPreferencesUpdateInputSchema>;
+
+export const emailPreferencesGetByTokenInputSchema = z
+  .object({
+    token: emailLinkTokenSchema,
+    locale: appLocaleSchema,
+  })
+  .strict();
+export type EmailPreferencesGetByTokenInput = z.infer<typeof emailPreferencesGetByTokenInputSchema>;
+
+export const emailPreferencesUpdateByTokenInputSchema = z
+  .object({
+    token: emailLinkTokenSchema,
+    locale: appLocaleSchema,
+    ...emailPreferencesChangesShape,
+  })
+  .strict();
+export type EmailPreferencesUpdateByTokenInput = z.infer<
+  typeof emailPreferencesUpdateByTokenInputSchema
+>;

package/src/schemas/feature-access.ts

@@ -0,0 +1,18 @@
+import { GATED_FEATURE_KEYS } from "@read-frog/definitions";
+import { z } from "zod";
+
+export const GatedFeatureKeySchema = z.enum(GATED_FEATURE_KEYS);
+export type GatedFeatureKey = z.infer<typeof GatedFeatureKeySchema>;
+
+export const FeatureAccessStatusInputSchema = z
+  .object({
+    featureKey: GatedFeatureKeySchema,
+  })
+  .strict();
+export type FeatureAccessStatusInput = z.infer<typeof FeatureAccessStatusInputSchema>;
+
+export const FeatureAccessStatusOutputSchema = z.object({
+  featureKey: GatedFeatureKeySchema,
+  allowed: z.boolean(),
+});
+export type FeatureAccessStatusOutput = z.infer<typeof FeatureAccessStatusOutputSchema>;

package/src/schemas/hosted-ai.ts

@@ -196,13 +196,16 @@ export const HostedAiRateLimitErrorDataSchema = z.object({
 });
 
 /**
+ * A recurring pool: the plan's credit for a day or a week, which refills at
+ * `resetAt`.
+ *
  * Deliberately free of dollar amounts and of the versioned policy id. Clients
  * render a consumption bar and a reset time, so a percentage and a period kind
  * are all they need, and neither leaks what a call costs us. `usedPercent`
  * counts settled spend only: including in-flight reservations would make the
  * bar jump forward and then back as each stream settles.
  */
-export const HostedAiCreditStatusSchema = z.strictObject({
+export const HostedAiRecurringCreditStatusSchema = z.strictObject({
   periodKind: HostedAiCreditPeriodKindSchema,
   usedPercent: z.number().min(0).max(100),
   resetAt: z.iso.datetime().nullable(),
@@ -214,6 +217,30 @@ export const HostedAiCreditStatusSchema = z.strictObject({
   features: z.array(HostedAiFeatureSchema).min(1),
 });
 
+/**
+ * A one-time pool, such as credit from a campaign or from support. It never
+ * refills: once spent or past `expiresAt` it is gone, so a client shows the
+ * expiry, not a reset. It is drawn on only after the plan's own pool for a
+ * feature is spent, or for a feature the plan does not fund. Listed until it
+ * expires, even when spent. Same fields as a recurring pool otherwise.
+ */
+export const HostedAiOneTimeCreditStatusSchema = z.strictObject({
+  periodKind: z.literal("once"),
+  usedPercent: z.number().min(0).max(100),
+  expiresAt: z.iso.datetime(),
+  features: z.array(HostedAiFeatureSchema).min(1),
+});
+
+/**
+ * One pool that can pay for Built-in AI, told apart by `periodKind`: a
+ * recurring `daily` or `weekly` pool refills at `resetAt`, a one-time (`once`)
+ * pool ends at `expiresAt`. Narrow on `periodKind` before reading either.
+ */
+export const HostedAiCreditPoolStatusSchema = z.discriminatedUnion("periodKind", [
+  HostedAiRecurringCreditStatusSchema,
+  HostedAiOneTimeCreditStatusSchema,
+]);
+
 export const HostedAiTierStatusSchema = z.strictObject({
   accessAllowed: z.boolean(),
   available: z.boolean(),
@@ -234,7 +261,21 @@ export const HostedAiFeatureStatusSchema = z.strictObject({
 });
 
 export const HostedAiStatusOutputSchema = z.strictObject({
-  credits: z.array(HostedAiCreditStatusSchema),
+  /**
+   * @deprecated Read `pools`. This lists the recurring pools only, never a
+   * one-time one: extensions released before mengxi-ream/read-frog#2395 look
+   * up a label for every entry's `periodKind`, and one they do not know
+   * crashes their usage page. They also throw if the field is missing.
+   *
+   * TODO(2026-11-07): remove once those extensions have drained (#710).
+   */
+  credits: z.array(HostedAiRecurringCreditStatusSchema),
+  /**
+   * Everything that can pay for a feature, in the order the server draws on it:
+   * the plan's recurring pools first, then one-time pools by soonest expiry. A
+   * feature can appear in several entries.
+   */
+  pools: z.array(HostedAiCreditPoolStatusSchema),
   features: z.strictObject({
     pageTranslation: HostedAiFeatureStatusSchema,
     customAction: HostedAiFeatureStatusSchema,
@@ -265,7 +306,9 @@ export type HostedAiCreditPolicyId = z.infer<typeof HostedAiCreditPolicyIdSchema
 export type HostedAiCreditPeriodKind = z.infer<typeof HostedAiCreditPeriodKindSchema>;
 export type HostedAiQuotaScope = z.infer<typeof HostedAiQuotaScopeSchema>;
 export type HostedAiRateLimitErrorData = z.infer<typeof HostedAiRateLimitErrorDataSchema>;
-export type HostedAiCreditStatus = z.infer<typeof HostedAiCreditStatusSchema>;
+export type HostedAiRecurringCreditStatus = z.infer<typeof HostedAiRecurringCreditStatusSchema>;
+export type HostedAiOneTimeCreditStatus = z.infer<typeof HostedAiOneTimeCreditStatusSchema>;
+export type HostedAiCreditPoolStatus = z.infer<typeof HostedAiCreditPoolStatusSchema>;
 export type HostedAiTierStatus = z.infer<typeof HostedAiTierStatusSchema>;
 export type HostedAiFeatureStatus = z.infer<typeof HostedAiFeatureStatusSchema>;
 export type HostedAiStatusOutput = z.infer<typeof HostedAiStatusOutputSchema>;