@read-frog/api-contract 0.24.0 → 0.26.0

package/src/schemas/web-sync.ts

@@ -0,0 +1,122 @@
+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",
+  "deleteCard",
+  // 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>;