@read-frog/api-contract 0.21.1 → 0.23.0

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"]);
 
@@ -159,13 +160,25 @@ 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",
@@ -196,13 +209,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,15 +230,47 @@ 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(),
   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),
@@ -234,7 +282,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,
@@ -261,11 +323,14 @@ 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>;
 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>;

package/src/schemas/notebase.ts

@@ -41,6 +41,8 @@ export const notebaseSchema = z.object({
   srsWeights: srsWeightsSchema.nullable(),
   // Selects the scheduler/curve; read-only, changed only by the FSRS-7 migration.
   srsModelVersion: srsModelVersionSchema,
+  // Null = awake; set = excluded from the combined review. Written by notebase.setSleep and auto sleep.
+  srsSleepingAt: z.date().nullable(),
   createdAt: z.date(),
   updatedAt: z.date(),
 });
@@ -144,6 +146,20 @@ export const NotebaseUpdateOutputSchema = z.object({
 });
 export type NotebaseUpdateOutput = z.infer<typeof NotebaseUpdateOutputSchema>;
 
+export const NotebaseSetSleepInputSchema = z
+  .object({
+    id: z.uuid(),
+    enabled: z.boolean(),
+  })
+  .strict();
+export type NotebaseSetSleepInput = z.infer<typeof NotebaseSetSleepInputSchema>;
+
+// txid is null when the notebase was already in the requested state: nothing to wait for.
+export const NotebaseSetSleepOutputSchema = z.object({
+  txid: z.number().nullable(),
+});
+export type NotebaseSetSleepOutput = z.infer<typeof NotebaseSetSleepOutputSchema>;
+
 export const NotebaseDeleteInputSchema = z.object({
   id: z.uuid(),
 });

package/src/schemas/speech.ts

@@ -109,5 +109,14 @@ export const speechSynthesizeInputSchema = z
   .strict();
 export type SpeechSynthesizeInput = z.infer<typeof speechSynthesizeInputSchema>;
 
-/** The audio, as an MP3 file. */
-export const speechSynthesizeOutputSchema = z.file();
+/**
+ * Where to download the audio, an MP3: a link to fetch at once, which stops
+ * working at `expiresAt`.
+ */
+export const speechSynthesizeOutputSchema = z
+  .object({
+    url: z.url(),
+    expiresAt: z.coerce.date(),
+  })
+  .strict();
+export type SpeechSynthesizeOutput = z.infer<typeof speechSynthesizeOutputSchema>;

package/src/schemas/srs.ts

@@ -13,7 +13,7 @@ import {
 import { z } from "zod";
 import { cardSchema } from "./card";
 import { notebaseSummarySchema } from "./notebase";
-import { timezoneSchema } from "./timezone";
+import { canonicalTimezoneSchema } from "./timezone";
 
 export { reviewRatingSchema, schedulingParamsSchema, SRS_REVIEW_DURATION_MS_MAX };
 export { timezoneSchema } from "./timezone";
@@ -45,7 +45,7 @@ export const srsReviewInputSchema = z
     id: z.uuid().optional(),
     rating: reviewRatingSchema,
     durationMs: z.number().int().min(0).max(SRS_REVIEW_DURATION_MS_MAX),
-    timezone: timezoneSchema,
+    timezone: canonicalTimezoneSchema,
   })
   .strict();
 export type SrsReviewInput = z.infer<typeof srsReviewInputSchema>;
@@ -67,7 +67,7 @@ export type SrsScheduleStatusStats = z.infer<typeof srsScheduleStatusStatsSchema
 export const srsScheduleStatusStatsInputSchema = z
   .object({
     notebaseIds: z.array(z.uuid()).optional(),
-    timezone: timezoneSchema,
+    timezone: canonicalTimezoneSchema,
   })
   .strict();
 export type SrsScheduleStatusStatsInput = z.infer<typeof srsScheduleStatusStatsInputSchema>;
@@ -77,7 +77,7 @@ export type SrsScheduleStatusStatsOutput = z.infer<typeof srsScheduleStatusStats
 
 export const srsRecentNotebaseScheduleStatusStatsInputSchema = z
   .object({
-    timezone: timezoneSchema,
+    timezone: canonicalTimezoneSchema,
   })
   .strict();
 export type SrsRecentNotebaseScheduleStatusStatsInput = z.infer<

package/src/schemas/stats.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { notebaseActivityStatsOutputSchema } from "./notebase-stats";
 import { srsActivityStatsOutputSchema } from "./srs-stats";
-import { timezoneSchema } from "./timezone";
+import { canonicalTimezoneSchema } from "./timezone";
 
 const statsNotebaseIdsSchema = z
   .array(z.uuid())
@@ -13,7 +13,7 @@ export const statsInputSchema = z
     notebaseIds: statsNotebaseIdsSchema.optional(),
     from: z.iso.date().optional(),
     to: z.iso.date(),
-    timezone: timezoneSchema,
+    timezone: canonicalTimezoneSchema,
   })
   .strict()
   .refine((input) => !input.from || input.from <= input.to, {

package/src/schemas/timezone.ts

@@ -1,3 +1,4 @@
+import { canonicalTimeZone } from "@read-frog/definitions";
 import { z } from "zod";
 
 // @ref https://zenn.dev/herp_inc/articles/js-intl-date-time-format-performance
@@ -46,3 +47,23 @@ export const timezoneSchema = z
     }
   }, "Invalid timezone");
 export type Timezone = z.infer<typeof timezoneSchema>;
+
+/**
+ * The zone a call reckons days in, under the name an account's zone is stored
+ * under (`canonicalTimeZone`): "Asia/Calcutta" arrives as "Asia/Kolkata" and
+ * "CST" as "America/Chicago", names that Temporal and a Debian Postgres both
+ * read. A fixed offset ("+08:00") is refused, as Postgres reads it with the
+ * opposite sign and would put the call's days on the wrong side of UTC.
+ */
+export const canonicalTimezoneSchema = timezoneSchema.transform((timezone, ctx) => {
+  const name = canonicalTimeZone(timezone);
+  if (!name) {
+    ctx.addIssue({
+      code: "custom",
+      message:
+        "Use an IANA time zone identifier instead of a fixed UTC offset. See https://www.iana.org/time-zones",
+    });
+    return z.NEVER;
+  }
+  return name;
+});

package/src/schemas/user.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { appLocaleSchema } from "./app-locale";
 import { timezoneSchema } from "./timezone";
 
 export const userEnsureTimezoneInputSchema = z
@@ -29,3 +30,35 @@ export const userUpdateTimezoneOutputSchema = z
   })
   .strict();
 export type UserUpdateTimezoneOutput = z.infer<typeof userUpdateTimezoneOutputSchema>;
+
+// The account's language, which emails are written in. `ensureLocale` only
+// fills it in when it is empty (the language www is showing on a signed-in
+// visit); `updateLocale` is the user choosing a language.
+export const userEnsureLocaleInputSchema = z
+  .object({
+    locale: appLocaleSchema,
+  })
+  .strict();
+export type UserEnsureLocaleInput = z.infer<typeof userEnsureLocaleInputSchema>;
+
+export const userEnsureLocaleOutputSchema = z
+  .object({
+    locale: appLocaleSchema,
+    updated: z.boolean(),
+  })
+  .strict();
+export type UserEnsureLocaleOutput = z.infer<typeof userEnsureLocaleOutputSchema>;
+
+export const userUpdateLocaleInputSchema = z
+  .object({
+    locale: appLocaleSchema,
+  })
+  .strict();
+export type UserUpdateLocaleInput = z.infer<typeof userUpdateLocaleInputSchema>;
+
+export const userUpdateLocaleOutputSchema = z
+  .object({
+    locale: appLocaleSchema,
+  })
+  .strict();
+export type UserUpdateLocaleOutput = z.infer<typeof userUpdateLocaleOutputSchema>;

package/src/contracts/beta-access.ts

@@ -1,14 +0,0 @@
-import { oc } from "@orpc/contract";
-import { BetaAccessStatusInputSchema, BetaAccessStatusOutputSchema } from "#/schemas/beta-access";
-
-export const betaAccessContract = {
-  status: oc
-    .route({
-      method: "GET",
-      path: "/beta-access/status",
-      summary: "Get beta access status for a feature",
-      tags: ["Beta Access"],
-    })
-    .input(BetaAccessStatusInputSchema)
-    .output(BetaAccessStatusOutputSchema),
-};

package/src/schemas/beta-access.ts

@@ -1,18 +0,0 @@
-import { BETA_FEATURE_KEYS } from "@read-frog/definitions";
-import { z } from "zod";
-
-export const BetaFeatureKeySchema = z.enum(BETA_FEATURE_KEYS);
-export type BetaFeatureKey = z.infer<typeof BetaFeatureKeySchema>;
-
-export const BetaAccessStatusInputSchema = z
-  .object({
-    featureKey: BetaFeatureKeySchema,
-  })
-  .strict();
-export type BetaAccessStatusInput = z.infer<typeof BetaAccessStatusInputSchema>;
-
-export const BetaAccessStatusOutputSchema = z.object({
-  featureKey: BetaFeatureKeySchema,
-  allowed: z.boolean(),
-});
-export type BetaAccessStatusOutput = z.infer<typeof BetaAccessStatusOutputSchema>;