@read-frog/api-contract 0.23.0 → 0.24.0

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>;

package/src/schemas/srs.ts

@@ -4,8 +4,10 @@ import {
   cardStateSchema,
   fsrsReviewLogSnapshotSchema,
   fsrsMemoryStateSchema,
+  POSTPONE_DAMAGE_THRESHOLD,
   reviewRatingSchema,
   scheduleStatusSchema,
+  schedulingParamsShape,
   schedulingParamsSchema,
   SRS_REVIEW_DURATION_MS_MAX,
   srsStepSchema,
@@ -259,3 +261,176 @@ function bytesToUuid(bytes: Uint8Array) {
     hex.slice(10, 16).join(""),
   ].join("-");
 }
+
+const count = z.number().int().nonnegative();
+
+export const srsBacklogStatsInputSchema = z
+  .object({
+    notebaseIds: z.array(z.uuid()).optional(),
+    timezone: canonicalTimezoneSchema,
+  })
+  .strict();
+export type SrsBacklogStatsInput = z.infer<typeof srsBacklogStatsInputSchema>;
+
+/**
+ * An Awake notebase with a positive daily review limit whose overdue reviews
+ * fill at least `BACKLOG_PROMPT_DAYS.badge` days.
+ */
+export const srsBacklogStatsSchema = z.object({
+  overdueReviewCount: count.describe(
+    "Review cards whose due date is before the start of today's study day.",
+  ),
+  dailyLimit: z
+    .number()
+    .int()
+    .positive()
+    .describe(
+      "The notebase's own daily review limit, which the backlog is measured against. Always positive: a notebase with no daily reviews (0) or an unlimited limit (-1) is never listed.",
+    ),
+  backlogDays: z
+    .number()
+    .nonnegative()
+    .describe("Days of reviews the backlog fills at that limit: overdueReviewCount / dailyLimit."),
+});
+export type SrsBacklogStats = z.infer<typeof srsBacklogStatsSchema>;
+
+/** Only the notebases that get the badge; the rest are absent. */
+export const srsBacklogStatsOutputSchema = z.record(z.uuid(), srsBacklogStatsSchema);
+export type SrsBacklogStatsOutput = z.infer<typeof srsBacklogStatsOutputSchema>;
+
+const rescheduleDailyLimitSchema = z.number().int().positive();
+
+export const srsPreviewPostponeInputSchema = z
+  .object({
+    notebaseId: z.uuid(),
+    timezone: canonicalTimezoneSchema,
+    dailyLimit: rescheduleDailyLimitSchema.optional(),
+    flattenFullRange: z
+      .boolean()
+      .optional()
+      .describe("Flatten levels every plannable day (180) instead of only the chart days."),
+  })
+  .strict();
+export type SrsPreviewPostponeInput = z.infer<typeof srsPreviewPostponeInputSchema>;
+
+const postponeThresholdSchema = z
+  .number()
+  .min(POSTPONE_DAMAGE_THRESHOLD.min)
+  .max(POSTPONE_DAMAGE_THRESHOLD.max);
+
+const postponeDaySchema = z.object({
+  day: z.number().int().positive(),
+  postponed: count,
+  rSum: z.number(),
+});
+
+const rescheduleBaselineDaySchema = z.object({
+  day: z.number().int().positive(),
+  scheduled: count,
+  rSum: z.number().nullable(),
+});
+export type RescheduleBaselineDay = z.infer<typeof rescheduleBaselineDaySchema>;
+
+export const spreadDaySchema = z.object({
+  day: count,
+  scheduled: count,
+  backlog: count,
+  backlogRSum: z.number(),
+  surplusIn: count,
+  surplusRSum: z.number(),
+  surplusStay: count,
+  surplusOut: count,
+});
+export type SpreadDay = z.infer<typeof spreadDaySchema>;
+
+const spreadKeptSchema = z.object({
+  stuck: count,
+  noRoom: count,
+});
+
+export const flattenStepSchema = z.object({
+  checked: z.boolean(),
+  fromToday: count,
+  fromFuture: count,
+  fromDays: count,
+  kept: spreadKeptSchema,
+  qSuggest: count,
+  meanRAfter: z.number(),
+  days: z.array(spreadDaySchema),
+  /** Cards Postpone already moved that this Flatten moves again, and their R under Postpone. */
+  postponedAgain: z.object({ count, rSum: z.number() }),
+});
+export type FlattenStep = z.infer<typeof flattenStepSchema>;
+
+/** One threshold's Postpone alone, before its Flatten option is attached. */
+export const postponeSummarySchema = z.object({
+  threshold: postponeThresholdSchema,
+  moved: count,
+  overflowToday: count,
+  meanRiBefore: z.number(),
+  meanRAfter: z.number(),
+  days: z.array(postponeDaySchema),
+});
+export type PostponeSummary = z.infer<typeof postponeSummarySchema>;
+
+export const postponeStepSchema = postponeSummarySchema.extend({
+  flatten: flattenStepSchema.nullable(),
+});
+export type PostponeStep = z.infer<typeof postponeStepSchema>;
+
+export const postponePlanSchema = z.object({
+  planId: z.string(),
+  limit: z.number().int().positive(),
+  steps: z.array(postponeStepSchema),
+  skipped: z.object({
+    belowFloor: count,
+    maxInterval: count,
+    invalid: count,
+  }),
+});
+export type PostponePlanSummary = z.infer<typeof postponePlanSchema>;
+
+const rescheduleReadySchema = z.object({
+  status: z.literal("ready"),
+  expiresAt: z.date(),
+  q: z.number().int().positive(),
+  qConfigured: schedulingParamsShape.reviewsPerDay,
+  qMax: z.number().int().positive(),
+  overdueReviewCount: count,
+  dueTodayReviewCount: count,
+  usedToday: count,
+});
+
+export const srsPreviewPostponeOutputSchema = z.discriminatedUnion("status", [
+  rescheduleReadySchema.extend({
+    plan: postponePlanSchema,
+    suggested: postponePlanSchema.nullable(),
+    baseline: z.array(rescheduleBaselineDaySchema),
+  }),
+  z.object({ status: z.literal("quotaZero") }),
+  z.object({ status: z.literal("invalidWeights") }),
+]);
+export type SrsPreviewPostponeOutput = z.infer<typeof srsPreviewPostponeOutputSchema>;
+
+const rescheduleApplyInputSchema = z.object({
+  notebaseId: z.uuid(),
+  planId: z.string().min(1),
+  unlimited: z.boolean().optional(),
+});
+
+export const srsApplyPostponeInputSchema = rescheduleApplyInputSchema
+  .extend({
+    threshold: postponeThresholdSchema,
+    flatten: z.boolean().optional(),
+  })
+  .strict();
+export type SrsApplyPostponeInput = z.infer<typeof srsApplyPostponeInputSchema>;
+
+export const srsRescheduleApplyOutputSchema = z.object({
+  moved: count,
+  txid: z.number().nullable(),
+  reviewsPerDay: schedulingParamsShape.reviewsPerDay,
+});
+export type SrsRescheduleApplyOutput = z.infer<typeof srsRescheduleApplyOutputSchema>;
+export const srsApplyPostponeOutputSchema = srsRescheduleApplyOutputSchema;
+export type SrsApplyPostponeOutput = z.infer<typeof srsApplyPostponeOutputSchema>;