src/contract/media.ts

Functions

Imports

It imports src/contract/base.ts. Imported by src/contract.ts.

Source

1// The media group (v0.2.0, writes v0.4.0, lenses v0.6.0).
2
3import { z } from "zod";
4import { ChangeId, SortDir, Timestamp, Version } from "./base.js";
5
6/** The largest upload any site may declare: well under a Worker's request body limit. */
7export const MAX_MEDIA_BYTES = 25 * 1024 * 1024;
8
9/**
10 * What a site accepts as an upload, declared by the site (v0.2.0). `types` are MIME types, such as
11 * image/png; the package refuses anything else before the site sees a byte.
12 */
13export const MediaUploadLimits = z.object({
14  maxBytes: z.number().int().min(1).max(MAX_MEDIA_BYTES),
15  types: z.array(z.string().regex(/^[a-z]+\/[a-z0-9.+-]+$/)).min(1).max(50),
16});
17
18/**
19 * The ready-made views of a library (v0.6.0), each optional per site: files nothing uses (by the
20 * site's own reference check), files with no alt text, and files larger than LARGE_MEDIA_BYTES.
21 */
22export const MEDIA_LENSES = ["unattached", "no-alt", "large"] as const;
23export const MediaLens = z.enum(MEDIA_LENSES);
24export const LARGE_MEDIA_BYTES = 1024 * 1024;
25
26/**
27 * A site's id for one media file: its storage key, such as 2026/09/photo-a1b2.webp. Segments are
28 * joined by "/", and none may be empty, "." or "..", so an id is never a path out of the store.
29 */
30export const MediaId = z
31  .string()
32  .max(300)
33  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/)
34  .refine((id) => !id.split("/").some((part) => part === "." || part === ".."), "An id segment may not be . or ..");
35
36/** One place a file is used, as the site's own reference check found it. */
37export const MediaUse = z.object({
38  /** What uses it, such as "post". */
39  type: z.string().min(1).max(64),
40  id: z.string().min(1).max(300),
41  title: z.string().max(1000),
42  /** Where in it, such as "cover image" or "line 12". */
43  detail: z.string().max(500),
44});
45
46/** A tag: lower case words joined by single hyphens, so the same tag is always spelled one way. */
47export const MediaTag = z.string().min(1).max(32).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
48
49/** A file's whole tag set (v0.4.0). The most any file carries is 12. */
50export const MediaTags = z.array(MediaTag).max(12);
51
52export const MediaItem = z.object({
53  id: MediaId,
54  /** Where the site serves it: a path on the site, such as /media/2026/09/photo.webp, or a full URL. */
55  url: z.string().min(1).max(2000).refine((u) => u.startsWith("/") || /^https:\/\//.test(u), "A path or an https URL"),
56  /** The name it was uploaded with, when the site kept it. */
57  filename: z.string().max(300).nullable(),
58  contentType: z.string().min(1).max(200),
59  bytes: z.number().int().min(0),
60  width: z.number().int().min(1).nullable(),
61  height: z.number().int().min(1).nullable(),
62  alt: z.string().max(2000),
63  uploadedAt: Timestamp.nullable(),
64  /** False for files the site will never delete through this API, such as its own static assets. */
65  deletable: z.boolean(),
66  /**
67   * Opaque, like a content version (v0.4.0): it identifies the file's editable metadata, so alt,
68   * tags and trash state each move it. Present on a site that offers any media write.
69   */
70  version: Version.optional(),
71  /** The file's tags (v0.4.0), present on a site that keeps them. */
72  tags: MediaTags.optional(),
73  /** When the file was moved to the trash (v0.4.0); null or absent when it is in the library. */
74  trashedAt: Timestamp.nullable().optional(),
75});
76
77/** One file with the places it is used: what a delete would be refused over. */
78export const MediaDetail = MediaItem.extend({
79  usedBy: z.array(MediaUse),
80});
81
82/** What a media list can be sorted by (v0.6.0). added runs newest first, size largest first and name A to Z, unless `dir` says otherwise. */
83export const MEDIA_SORTS = ["added", "name", "size"] as const;
84
85export const MediaListQuery = z.object({
86  q: z.string().max(200).optional(),
87  /** v0.6.0, on a site that lists the lens in capabilities.mediaLenses; any other site answers 501. */
88  lens: MediaLens.optional(),
89  /** v0.6.0. A site that sorts says so in the answer's `sorted`. */
90  sort: z.enum(MEDIA_SORTS).optional(),
91  dir: SortDir.optional(),
92  /** Only files carrying this tag (v0.4.0). A site without tags ignores it. */
93  tag: MediaTag.optional(),
94  /** "only" lists the trash (v0.4.0). Without it the trash is left out. A site without a trash ignores it. */
95  trashed: z.enum(["only"]).optional(),
96  cursor: z.string().max(500).optional(),
97  limit: z.coerce.number().int().min(1).max(200).default(50),
98});
99
100export const MediaList = z.object({
101  items: z.array(MediaItem),
102  nextCursor: z.string().nullable(),
103  /** How many files match across every page (v0.6.0), where the site can count them. */
104  total: z.number().int().min(0).optional(),
105  /** The order the site applied (v0.6.0). Absent: the site did not sort as asked. */
106  sorted: z.object({ sort: z.enum(MEDIA_SORTS), dir: SortDir }).optional(),
107});
108
109/**
110 * An upload is the file's own bytes as the body, its type as Content-Type, and these as the query:
111 * no base64, so a file costs its own size and no more.
112 */
113export const MediaUploadQuery = z.object({
114  // A file name may not hold control characters, on purpose.
115  // oxlint-disable-next-line no-control-regex
116  filename: z.string().min(1).max(200).regex(/^[^/\\\u0000-\u001f]+$/, "A file name, with no path"),
117  alt: z.string().max(2000).default(""),
118  changeId: ChangeId,
119});
120
121export const MediaDeleteQuery = z.object({
122  changeId: ChangeId,
123});
124
125export const MediaDeleteResult = z.object({
126  id: MediaId,
127  deleted: z.literal(true),
128  changeId: ChangeId,
129});
130
131// ---------- media writes (v0.4.0)
132
133/** Every media metadata write names the version the caller last saw and Carrel's change id. */
134export const MediaAltInput = z.object({
135  alt: z.string().max(2000),
136  expectedVersion: Version,
137  changeId: ChangeId,
138});
139
140/** The file's whole tag set after the write. */
141export const MediaTagsInput = z.object({
142  tags: MediaTags,
143  expectedVersion: Version,
144  changeId: ChangeId,
145});
146
147/** The body of a trash and of a restore. */
148export const MediaTrashInput = z.object({
149  expectedVersion: Version,
150  changeId: ChangeId,
151});
152
153export const MediaWriteResult = z.object({
154  id: MediaId,
155  /** The file's version after the write. */
156  version: Version,
157  changeId: ChangeId,
158});
159
160export const MEDIA_BULK_OPS = ["trash", "restore", "delete", "add-tags", "remove-tags"] as const;
161export const MAX_MEDIA_BULK = 100;
162
163/** One file in a bulk write, with its own change id so each file has its own authorship record. */
164export const MediaBulkItem = z.object({
165  id: MediaId,
166  /** Required for every op but delete, which is the site's reference check and carries no version. */
167  expectedVersion: Version.optional(),
168  changeId: ChangeId,
169});
170
171export const MediaBulkInput = z.object({
172  op: z.enum(MEDIA_BULK_OPS),
173  /** For add-tags and remove-tags only: the tags to add to, or take from, each file. */
174  tags: MediaTags.optional(),
175  items: z.array(MediaBulkItem).min(1).max(MAX_MEDIA_BULK),
176});
177
178/** The outcome of one file. A refusal for one file never stops the others. */
179export const MediaBulkOutcome = z.discriminatedUnion("ok", [
180  z.object({
181    ok: z.literal(true),
182    id: MediaId,
183    changeId: ChangeId,
184    /** The file's version after the write; absent after a delete. */
185    version: Version.optional(),
186  }),
187  z.object({
188    ok: z.literal(false),
189    id: MediaId,
190    changeId: ChangeId,
191    error: z.enum(["not-found", "version-conflict", "refused", "invalid", "internal"]),
192    message: z.string(),
193    /** On version-conflict: what the site holds now. */
194    currentVersion: Version.nullable().optional(),
195    /** On a refused delete: every place the file is used. */
196    usedBy: z.array(MediaUse).optional(),
197  }),
198]);
199
200/** The request as a whole answers 200 whenever it was well formed: each file's result is its own. */
201export const MediaBulkResult = z.object({
202  op: z.enum(MEDIA_BULK_OPS),
203  results: z.array(MediaBulkOutcome),
204});
205
206/** Empty the trash: delete for good every file in it, each through the site's own reference check. */
207export const MediaTrashEmptyInput = z.object({
208  /** The base of each file's own change id: file n is recorded as `<changeId>-<n>`, so each has its own authorship record. */
209  changeId: ChangeId,
210});
211
212/** The most files one empty-trash request deletes. When more remain, `more` is true and the caller sends it again. */
213export const MAX_TRASH_EMPTY = 100;
214
215export const MediaTrashEmptyResult = z.object({
216  changeId: ChangeId,
217  /** The ids deleted for good. */
218  deleted: z.array(MediaId),
219  /** Trashed files the site would not delete (still used by a post, for one); they stay in the trash. */
220  refused: z.array(z.object({ id: MediaId, message: z.string(), usedBy: z.array(MediaUse).optional() })),
221  /** True when the trash held more than one request handles. */
222  more: z.boolean(),
223});
224
225export type MediaUploadLimits = z.infer<typeof MediaUploadLimits>;
226export type MediaUse = z.infer<typeof MediaUse>;
227export type MediaItem = z.infer<typeof MediaItem>;
228export type MediaDetail = z.infer<typeof MediaDetail>;
229export type MediaListQuery = z.infer<typeof MediaListQuery>;
230export type MediaLens = z.infer<typeof MediaLens>;
231export type MediaSort = (typeof MEDIA_SORTS)[number];
232export type MediaList = z.infer<typeof MediaList>;
233export type MediaUploadQuery = z.infer<typeof MediaUploadQuery>;
234export type MediaDeleteResult = z.infer<typeof MediaDeleteResult>;
235export type MediaTags = z.infer<typeof MediaTags>;
236export type MediaAltInput = z.infer<typeof MediaAltInput>;
237export type MediaTagsInput = z.infer<typeof MediaTagsInput>;
238export type MediaTrashInput = z.infer<typeof MediaTrashInput>;
239export type MediaWriteResult = z.infer<typeof MediaWriteResult>;
240export type MediaBulkItem = z.infer<typeof MediaBulkItem>;
241export type MediaBulkInput = z.infer<typeof MediaBulkInput>;
242export type MediaBulkOutcome = z.infer<typeof MediaBulkOutcome>;
243export type MediaBulkResult = z.infer<typeof MediaBulkResult>;
244export type MediaTrashEmptyInput = z.infer<typeof MediaTrashEmptyInput>;
245export type MediaTrashEmptyResult = z.infer<typeof MediaTrashEmptyResult>;