@read-frog/api-contract 0.23.0 → 0.25.0

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"]);
@@ -36,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>;
@@ -116,6 +133,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/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/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

@@ -32,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();
 
@@ -182,8 +185,14 @@ 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"]);
@@ -254,6 +263,12 @@ 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(),

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/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(),
 });

package/src/schemas/pdf-translation.ts

@@ -0,0 +1,240 @@
+import { PDF_TRANSLATION_MAX_BATCH_FILES } from "@read-frog/definitions";
+import { z } from "zod";
+import { HostedAiModelTierSchema } from "./hosted-ai";
+
+export const pdfTranslationJobStatusSchema = z.enum([
+  "queued",
+  "running",
+  "cancel_requested",
+  "succeeded",
+  "failed",
+  "cancelled",
+  // Succeeded, but the translation is past its retention and gone.
+  "expired",
+]);
+export type PdfTranslationJobStatus = z.infer<typeof pdfTranslationJobStatusSchema>;
+
+/**
+ * The two PDFs one translation makes: the translation alone, with the
+ * original's layout, and the original and translated pages side by side.
+ */
+export const pdfTranslationOutputVariantSchema = z.enum(["translated", "bilingual"]);
+export type PdfTranslationOutputVariant = z.infer<typeof pdfTranslationOutputVariantSchema>;
+
+const languageSchema = z
+  .string()
+  .min(2)
+  .max(40)
+  .regex(/^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$/i);
+
+export const pdfTranslationRequestUploadInputSchema = z
+  .object({
+    fileName: z
+      .string()
+      .trim()
+      .min(1)
+      .max(255)
+      .refine((fileName) => fileName.toLowerCase().endsWith(".pdf"), {
+        message: "fileName must end with .pdf",
+      }),
+    // The exact size: the upload is signed for it, and storage refuses any other file.
+    fileByteSize: z.number().int().min(1),
+  })
+  .strict();
+export type PdfTranslationRequestUploadInput = z.infer<
+  typeof pdfTranslationRequestUploadInputSchema
+>;
+
+export const pdfTranslationRequestUploadOutputSchema = z
+  .object({
+    uploadId: z.uuid(),
+    // A PUT of the file to `url` with exactly these headers.
+    upload: z
+      .object({
+        url: z.url(),
+        headers: z.record(z.string(), z.string()),
+      })
+      .strict(),
+    expiresAt: z.coerce.date(),
+  })
+  .strict();
+export type PdfTranslationRequestUploadOutput = z.infer<
+  typeof pdfTranslationRequestUploadOutputSchema
+>;
+
+export const pdfTranslationSubmitInputSchema = z
+  .object({
+    // The PDFs to translate with the same settings, in the order they run.
+    uploadIds: z
+      .array(z.uuid())
+      .min(1)
+      .max(PDF_TRANSLATION_MAX_BATCH_FILES)
+      .refine((ids) => new Set(ids).size === ids.length, {
+        message: "uploadIds must not repeat",
+      }),
+    // A retry with the same key returns the jobs the first request made.
+    idempotencyKey: z.string().trim().min(1).max(200),
+    // Only the target: the model works out the PDF's own language from its text.
+    targetLanguage: languageSchema,
+    // Under the same rules as every Built-in AI feature: advance is Ultra's.
+    modelTier: HostedAiModelTierSchema,
+  })
+  .strict();
+export type PdfTranslationSubmitInput = z.infer<typeof pdfTranslationSubmitInputSchema>;
+
+export const pdfTranslationJobIdInputSchema = z
+  .object({
+    id: z.uuid(),
+  })
+  .strict();
+export type PdfTranslationJobIdInput = z.infer<typeof pdfTranslationJobIdInputSchema>;
+
+export const pdfTranslationOutputInputSchema = z
+  .object({
+    id: z.uuid(),
+    variant: pdfTranslationOutputVariantSchema,
+  })
+  .strict();
+export type PdfTranslationOutputInput = z.infer<typeof pdfTranslationOutputInputSchema>;
+
+export const pdfTranslationListInputSchema = z.object({}).strict();
+export type PdfTranslationListInput = z.infer<typeof pdfTranslationListInputSchema>;
+
+export const pdfTranslationJobResourceSchema = z
+  .object({
+    id: z.uuid(),
+    status: pdfTranslationJobStatusSchema,
+    sourceFileName: z.string(),
+    targetLanguage: z.string(),
+    modelTier: HostedAiModelTierSchema,
+    // The PDFs submitted together, which run one at a time in this order.
+    batchId: z.uuid(),
+    batchPosition: z.number().int().min(0),
+    // How many of the account's translations run before a queued one: null
+    // once it has started, or when it never will.
+    waitingAhead: z.number().int().min(0).nullable(),
+    // A Free account's one translation, which it can read here but not download.
+    freeTrial: z.boolean(),
+    // Which PDFs a succeeded job has. A job translated before both were made
+    // has only the one it asked for; any other job has neither.
+    outputs: z
+      .object({
+        translated: z.boolean(),
+        bilingual: z.boolean(),
+      })
+      .strict(),
+    pageCount: z.number().int().min(1),
+    progressStage: z.string().nullable(),
+    progressPercent: z.number().min(0).max(100),
+    // Built-in AI credit, in billionths of a US dollar: what admission
+    // expected, and what the model calls have used so far.
+    estimatedCostNanoUsd: z.number().int().min(0),
+    chargedCostNanoUsd: z.number().int().min(0),
+    error: z
+      .object({
+        category: z.string(),
+        message: z.string(),
+      })
+      .strict()
+      .nullable(),
+    // The worker version that last ran the job, for support.
+    workerRelease: z.string().nullable(),
+    createdAt: z.coerce.date(),
+    startedAt: z.coerce.date().nullable(),
+    completedAt: z.coerce.date().nullable(),
+    // When a succeeded job's translation stops being downloadable.
+    outputExpiresAt: z.coerce.date().nullable(),
+  })
+  .strict();
+export type PdfTranslationJobResource = z.infer<typeof pdfTranslationJobResourceSchema>;
+
+export const pdfTranslationListOutputSchema = z
+  .object({
+    items: z.array(pdfTranslationJobResourceSchema),
+  })
+  .strict();
+export type PdfTranslationListOutput = z.infer<typeof pdfTranslationListOutputSchema>;
+
+/** What a submission made: its batch, and one job per PDF in their order. */
+export const pdfTranslationSubmitOutputSchema = z
+  .object({
+    batchId: z.uuid(),
+    jobs: z.array(pdfTranslationJobResourceSchema).min(1),
+  })
+  .strict();
+export type PdfTranslationSubmitOutput = z.infer<typeof pdfTranslationSubmitOutputSchema>;
+
+/** A job, and every job of its batch in their order (itself included). */
+export const pdfTranslationGetOutputSchema = z
+  .object({
+    job: pdfTranslationJobResourceSchema,
+    batch: z.array(pdfTranslationJobResourceSchema).min(1),
+  })
+  .strict();
+export type PdfTranslationGetOutput = z.infer<typeof pdfTranslationGetOutputSchema>;
+
+export const pdfTranslationStatusInputSchema = z.object({}).strict();
+export type PdfTranslationStatusInput = z.infer<typeof pdfTranslationStatusInputSchema>;
+
+export const pdfTranslationStatusOutputSchema = z
+  .object({
+    // An account nothing funds translates one PDF, once, on the normal tier:
+    // 1 until it has, and always 0 for a funded account.
+    freeTrialsRemaining: z.number().int().min(0),
+    /**
+     * Whether Built-in AI credit pays for PDF translation on the normal tier:
+     * a paid plan, or credit the account was given for every feature. Only a
+     * funded account submits more than one PDF or downloads a translation.
+     */
+    funded: z.boolean(),
+  })
+  .strict();
+export type PdfTranslationStatusOutput = z.infer<typeof pdfTranslationStatusOutputSchema>;
+
+export const pdfTranslationDownloadOutputSchema = z
+  .object({
+    url: z.url(),
+    expiresAt: z.coerce.date(),
+  })
+  .strict();
+export type PdfTranslationDownloadOutput = z.infer<typeof pdfTranslationDownloadOutputSchema>;
+
+export const pdfTranslationPreviewOutputSchema = z
+  .object({
+    url: z.url(),
+    expiresAt: z.coerce.date(),
+    /**
+     * Whether the URL opens the free translation's copy with the Read Frog
+     * watermark, which an account nothing funds reads: upgrading opens the
+     * PDF itself.
+     */
+    watermarked: z.boolean(),
+  })
+  .strict();
+export type PdfTranslationPreviewOutput = z.infer<typeof pdfTranslationPreviewOutputSchema>;
+
+export const pdfTranslationDeleteOutputSchema = z
+  .object({
+    id: z.uuid(),
+  })
+  .strict();
+export type PdfTranslationDeleteOutput = z.infer<typeof pdfTranslationDeleteOutputSchema>;
+
+export const PdfTranslationInsufficientCreditDataSchema = z.strictObject({
+  estimatedCostNanoUsd: z.number().int().min(0),
+  remainingNanoUsd: z.number().int().min(0),
+  resetAt: z.iso.datetime().nullable(),
+});
+export type PdfTranslationInsufficientCreditData = z.infer<
+  typeof PdfTranslationInsufficientCreditDataSchema
+>;
+
+/**
+ * Which of a submission's PDFs a refusal is about, so the page can point at
+ * it. For an upload an earlier request used up, also the translation it made.
+ */
+export const PdfTranslationUploadErrorDataSchema = z.strictObject({
+  uploadId: z.uuid(),
+  jobId: z.uuid().optional(),
+});
+export type PdfTranslationUploadErrorData = z.infer<typeof PdfTranslationUploadErrorDataSchema>;