dto.ts · Source

dto.tsapps/api/src/modules/blocks/dto.tsraw ← blocks5,721 B← Back to the app
1import { z } from "zod";
2import { BLOCK_TYPES } from "../../constants.js";
3 
4/**
5 * The REST block type, case-tolerant on input.
6 *
7 * The DB/REST wire enum is UPPERCASE (`BLOCK_TYPES`), but the web editor's
8 * codec is lowercase (`file`, `heading_1`, …). The realtime gateway already
9 * reconciles the two at its boundary (`prisma-store.ts` `codecToDbType` /
10 * `dbToCodecType`); the REST path now does the same so a block created via
11 * `POST /pages/:id/blocks` with the codec case stores and returns the DB
12 * case. UPPERCASE input is unchanged (backward compatible — existing
13 * integration tests send and expect `PARAGRAPH`/`FILE`/…).
14 */
15const blockTypeSchema = z
16  .string()
17  .min(1)
18  .transform((t) => t.toUpperCase())
19  .pipe(z.enum(BLOCK_TYPES));
20 
21/**
22 * Block content: the canonical shape is an object (e.g. `{ text }`), but the
23 * web InlineEditor round-trips content as an HTML STRING (its MVP storage
24 * model — see the API's own `blockText` in modules/ai/prompts.ts, which
25 * documents both shapes must stay readable). Accepting a string here is what
26 * lets the editor's `PATCH /blocks/:id` and batch `op:"update"` saves persist
27 * web-typed text instead of 400ing.
28 */
29const blockContentSchema = z.union([z.string(), z.record(z.unknown())]);
30 
31export const CreateBlockDto = z.object({
32  type: blockTypeSchema,
33  // The web editor stores text as an HTML STRING (the InlineEditor storage
34  // model) — accept string OR record here, exactly like UpdateBlockDto. A
35  // record-only schema 400'd every web paste/import (content: "<p>…</p>").
36  content: blockContentSchema.default({}),
37  properties: z.record(z.unknown()).default({}),
38  parentId: z.string().min(1).nullable().optional(),
39  afterBlockId: z.string().min(1).optional(),
40  beforeBlockId: z.string().min(1).optional(),
41  position: z.string().min(1).optional(),
42  /**
43   * Optional client-chosen block id (the web paste path generates
44   * `blk_`-prefixed ids so nested pastes can reference their parent by id
45   * in ONE batch). Uniqueness is enforced by the DB primary key — a
46   * collision aborts the whole batch (no partial application). Omitted →
47   * the server assigns a cuid (today's behavior).
48   */
49  id: z.string().min(1).max(128).optional()
50});
51export type CreateBlockInput = z.infer<typeof CreateBlockDto>;
52 
53export const DuplicateBlockDto = z.object({
54  parentId: z.string().min(1).nullable().optional(),
55  afterBlockId: z.string().min(1).optional()
56});
57export type DuplicateBlockInput = z.infer<typeof DuplicateBlockDto>;
58 
59export const UpdateBlockDto = z.object({
60  type: blockTypeSchema.optional(),
61  content: blockContentSchema.optional(),
62  properties: z.record(z.unknown()).optional(),
63  archived: z.boolean().optional(),
64  /**
65   * TASK-0123: optional optimistic-concurrency base. When present the write
66   * only applies if the block is still at exactly this version; otherwise a
67   * 409 CONFLICT `{ reason: "stale_version", actualVersion }` is returned.
68   * Omitted → the historical unconditional increment (unchanged behavior).
69   */
70  baseVersion: z.number().int().positive().optional()
71});
72export type UpdateBlockInput = z.infer<typeof UpdateBlockDto>;
73 
74export const MoveBlockDto = z.object({
75  parentId: z.string().min(1).nullable().optional(),
76  afterBlockId: z.string().min(1).optional(),
77  beforeBlockId: z.string().min(1).optional(),
78  position: z.string().min(1).optional()
79});
80export type MoveBlockInput = z.infer<typeof MoveBlockDto>;
81 
82const BatchUpsertOp = z.object({
83  op: z.literal("upsert"),
84  block: CreateBlockDto
85});
86const BatchDeleteOp = z.object({
87  op: z.literal("delete"),
88  blockId: z.string().min(1)
89});
90const BatchMoveOp = z.object({
91  op: z.literal("move"),
92  blockId: z.string().min(1),
93  move: MoveBlockDto
94});
95/**
96 * The web editor's debounced save (components/editor/block-save-queue.ts)
97 * flushes `op:"update"` ops — one per typed block — to this endpoint. The
98 * union used to omit it, so EVERY batched text save 400'd ("Invalid
99 * discriminator value") and the queue silently re-queued forever. The patch
100 * is the web's `BlockPatch` (content may be an HTML string — the InlineEditor
101 * storage model; type conversions clear properties, mirroring PATCH).
102 * `passthrough()` (rather than stripping unknown keys) so the client's
103 * field set is never silently dropped.
104 */
105const BatchUpdateOp = z.object({
106  op: z.literal("update"),
107  blockId: z.string().min(1),
108  patch: z
109    .object({
110      type: blockTypeSchema.optional(),
111      content: blockContentSchema.optional(),
112      properties: z.record(z.unknown()).optional(),
113      parentId: z.string().min(1).nullable().optional(),
114      position: z.string().min(1).optional()
115    })
116    .passthrough()
117});
118export const BatchBlocksDto = z.object({
119  pageId: z.string().min(1),
120  // The `pages.version` the client last read (the Phase-4 409-rebase path,
121  // now also the TASK-0092 flush serialization): a stale baseVersion → 409
122  // CONFLICT carrying the NEW version ("flush wins; REST sees fresh state
123  // on retry"). Omitted (legacy clients / import / AI / automation) → the
124  // write proceeds, still advancing the version so a concurrent realtime
125  // flush's CAS fails and rebases over the REST write (never clobbers it).
126  baseVersion: z.number().int().min(1).optional(),
127  ops: z.array(
128    z.discriminatedUnion("op", [BatchUpsertOp, BatchUpdateOp, BatchDeleteOp, BatchMoveOp])
129  ).min(1).max(200)
130});
131export type BatchBlocksInput = z.infer<typeof BatchBlocksDto>;
132 
133export const ListBlocksQuery = z.object({
134  parentId: z.string().nullable().optional(),
135  depth: z.union([z.enum(["1", "all"]), z.coerce.number().int().min(1)]).optional()
136});
137export type ListBlocksInput = z.infer<typeof ListBlocksQuery>;
138