@read-frog/api-contract 0.23.0 → 0.25.0

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,
@@ -152,7 +154,9 @@ export type SrsListCardRevlogsOutput = z.infer<typeof srsListCardRevlogsOutputSc
 export const srsReviewOutputSchema = z.object({
   card: cardSchema,
   revlog: srsRevlogSchema,
-  txid: z.number(),
+  // Null for an idempotent replay: it writes nothing, so no shape ever carries
+  // its transaction. Wait for the returned card and revlog instead.
+  txid: z.number().nullable(),
   // False when an idempotent replay returned an existing revlog instead of creating one.
   created: z.boolean(),
 });
@@ -259,3 +263,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>;

package/src/schemas/web-sync.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+
+// What the web app reports about keeping its Electric data live. Every field is
+// an enum, so each label the API counts them under has a fixed set of values.
+
+/** The shapes the web app syncs, by their names in `@repo/electric-contract`. */
+export const webSyncShapeSchema = z.enum([
+  "notebases",
+  "notebaseColumns",
+  "notebaseRows",
+  "cardTemplates",
+  "cards",
+  "revlogs",
+  "mediaAssets",
+]);
+export type WebSyncShape = z.infer<typeof webSyncShapeSchema>;
+
+/** The write whose change the page waited to see come back over Electric. */
+export const webSyncOperationSchema = z.enum([
+  // The review session's own writes.
+  "review",
+  // A review the server had already recorded: it waits for that review's card
+  // and revlog, as its own transaction wrote nothing.
+  "reviewReplay",
+  "undo",
+  "bury",
+  "suspend",
+  "deleteNote",
+  // A synced collection's own mutation handlers.
+  "insert",
+  "update",
+  "delete",
+  // Other writes that wait for their change.
+  "setSleep",
+  "srsSettings",
+  "cardStatus",
+  "createTemplate",
+  "updateTemplate",
+]);
+export type WebSyncOperation = z.infer<typeof webSyncOperationSchema>;
+
+/** How the shape that lagged was receiving live changes. */
+export const webSyncTransportSchema = z.enum(["sse", "longPoll"]);
+export type WebSyncTransport = z.infer<typeof webSyncTransportSchema>;
+
+/**
+ * A write wait is only reported once its first wait ran out: `recovered` when
+ * reconnecting the lagging shapes brought the change, `failed` when the page
+ * gave up on it.
+ */
+export const webSyncWriteOutcomeSchema = z.enum(["recovered", "failed"]);
+export type WebSyncWriteOutcome = z.infer<typeof webSyncWriteOutcomeSchema>;
+
+export const webSyncStreamErrorTypeSchema = z.enum([
+  // 401: the session ended.
+  "unauthorized",
+  // 403: the notebase was deleted, or is someone else's.
+  "forbidden",
+  // 400 and any other 4xx.
+  "badRequest",
+  "clientError",
+  // A response without Electric's headers: a proxy or CORS in the way.
+  "missingHeaders",
+  // Anything that is not an HTTP status: an unreadable body, a parse error.
+  "unexpected",
+]);
+export type WebSyncStreamErrorType = z.infer<typeof webSyncStreamErrorTypeSchema>;
+
+/** `initial` before the shape first loaded, when the page shows the error at once. */
+export const webSyncStreamPhaseSchema = z.enum(["initial", "live"]);
+export type WebSyncStreamPhase = z.infer<typeof webSyncStreamPhaseSchema>;
+
+export const webSyncPageSchema = z.enum(["reviewCombined", "reviewNotebase"]);
+export type WebSyncPage = z.infer<typeof webSyncPageSchema>;
+
+export const webSyncUnavailableReasonSchema = z.enum([
+  // A write's change never came back, even after reconnecting.
+  "syncTimeout",
+  // A shape stream stopped.
+  "streamFailed",
+  // The notebase is gone: its shapes answer 403.
+  "notebaseGone",
+]);
+export type WebSyncUnavailableReason = z.infer<typeof webSyncUnavailableReasonSchema>;
+
+export const webSyncEventSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("writeWait"),
+      operation: webSyncOperationSchema,
+      outcome: webSyncWriteOutcomeSchema,
+      transport: webSyncTransportSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("streamError"),
+      shape: webSyncShapeSchema,
+      errorType: webSyncStreamErrorTypeSchema,
+      phase: webSyncStreamPhaseSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("unavailable"),
+      page: webSyncPageSchema,
+      reason: webSyncUnavailableReasonSchema,
+    })
+    .strict(),
+]);
+export type WebSyncEvent = z.infer<typeof webSyncEventSchema>;
+
+/** A page sends what happened within a second or so as one batch. */
+export const WEB_SYNC_REPORT_MAX_EVENTS = 20;
+
+export const reportWebSyncInputSchema = z
+  .object({
+    events: z.array(webSyncEventSchema).min(1).max(WEB_SYNC_REPORT_MAX_EVENTS),
+  })
+  .strict();
+export type ReportWebSyncInput = z.infer<typeof reportWebSyncInputSchema>;