src/admin/media.ts

Functions

Imports

It imports src/admin/kit.ts, src/client.ts, src/contract.ts. Imported by src/admin.ts.

Source

1// The media half of the content kit: MediaLibrary's view data and its intents.
2
3import { SiteApiError } from "../client.js";
4import {
5  MEDIA_SORTS,
6  MediaId,
7  MediaLens,
8  MediaTag,
9  type Capabilities,
10  type SortDir,
11  type MediaDetail,
12  type MediaItem,
13  type MediaSort,
14  type MediaUploadLimits,
15} from "../contract.js";
16import {
17  type Permissions,
18  type ContentSource,
19  type IntentInput,
20  type Outcome,
21  type IntentResult,
22  PER_PAGE,
23  NOT_YOURS,
24  fieldOf,
25  texts,
26  text,
27  refused,
28  plural,
29  changeId,
30  recordDone,
31  targetsOf,
32  checkCount,
33  summarise,
34  result,
35  orNull,
36  Conflict,
37  eachItem,
38  absolute,
39} from "./kit.js";
40
41
42export interface MediaQuery {
43  q?: string;
44  tag?: string;
45  view?: "library" | "trash";
46  /** v0.6.0, where the site names the lens; dropped, never sent, where it does not. */
47  lens?: MediaLens;
48  sort?: MediaSort;
49  dir?: SortDir;
50  cursor?: string;
51  /** The file open in the inspector. */
52  inspect?: string;
53}
54
55/** A file as the library shows it: the site's item, plus the absolute address a browser loads. */
56export type MediaRow = MediaItem & { src: string };
57
58export interface MediaData {
59  site: { id: string; name: string };
60  query: MediaQuery;
61  rows: MediaRow[];
62  page: {
63    nextCursor: string | null;
64    total?: number;
65    /** True when the rows were sorted on this page only, because the site's list does not sort. */
66    sortedOnPage?: boolean;
67  };
68  /** The file in the inspector with every place it is used; null when the site has no such file. */
69  detail?: (MediaDetail & { src: string }) | null;
70  offers: {
71    /** False on a site with no media manager: every other offer is then false. */
72    media: boolean;
73    upload: MediaUploadLimits | null;
74    alt: boolean;
75    tags: boolean;
76    trash: boolean;
77    delete: boolean;
78    /** The lenses the site answers (v0.6.0); empty where it answers none. */
79    lenses: MediaLens[];
80  };
81  can: Permissions;
82}
83
84export function readMediaQuery(search: URLSearchParams): MediaQuery {
85  const q = search.get("q")?.trim().slice(0, 200);
86  const tag = search.get("tag")?.trim().toLowerCase();
87  const cursor = search.get("cursor")?.slice(0, 500);
88  const inspect = search.get("inspect") ?? "";
89  const lens = MediaLens.safeParse(search.get("lens"));
90  const sort = search.get("sort");
91  const dir = search.get("dir");
92  return {
93    ...(q ? { q } : {}),
94    ...(lens.success ? { lens: lens.data } : {}),
95    ...(sort && (MEDIA_SORTS as readonly string[]).includes(sort) ? { sort: sort as MediaSort } : {}),
96    ...(dir === "asc" || dir === "desc" ? { dir } : {}),
97    ...(tag && MediaTag.safeParse(tag).success ? { tag } : {}),
98    ...(search.get("view") === "trash" ? { view: "trash" as const } : {}),
99    ...(cursor ? { cursor } : {}),
100    ...(MediaId.safeParse(inspect).success ? { inspect } : {}),
101  };
102}
103
104function mediaOffers(capabilities: Capabilities): MediaData["offers"] {
105  const media = capabilities.media === true && capabilities.mediaUpload !== undefined;
106  return {
107    media,
108    upload: media ? capabilities.mediaUpload! : null,
109    alt: media && capabilities.mediaAlt === true,
110    tags: media && capabilities.mediaTags === true,
111    trash: media && capabilities.mediaTrash === true,
112    delete: media,
113    lenses: media ? [...(capabilities.mediaLenses ?? [])] : [],
114  };
115}
116
117const MEDIA_BY: Record<MediaSort, (a: MediaItem, b: MediaItem) => number> = {
118  added: (a, b) => (b.uploadedAt ?? "").localeCompare(a.uploadedAt ?? ""),
119  size: (a, b) => b.bytes - a.bytes,
120  name: (a, b) => (a.filename ?? a.id).localeCompare(b.filename ?? b.id),
121};
122
123/** One page of one site's media library, as MediaLibrary renders it. */
124export async function loadMedia(source: ContentSource, query: MediaQuery = {}): Promise<MediaData> {
125  const offers = mediaOffers((await source.client.meta()).capabilities);
126  const base = { site: { id: source.site.id, name: source.site.name }, query, offers, can: source.can };
127  if (!offers.media) return { ...base, rows: [], page: { nextCursor: null } };
128  const list = await source.client.media.list({
129    limit: PER_PAGE,
130    ...(query.q ? { q: query.q } : {}),
131    ...(query.tag && offers.tags ? { tag: query.tag } : {}),
132    ...(query.view === "trash" && offers.trash ? { trashed: "only" as const } : {}),
133    ...(query.lens && offers.lenses.includes(query.lens) ? { lens: query.lens } : {}),
134    ...(query.sort ? { sort: query.sort, ...(query.dir ? { dir: query.dir } : {}) } : {}),
135    ...(query.cursor ? { cursor: query.cursor } : {}),
136  });
137  let items = list.items;
138  // A site that sorted says so (v0.6.0); otherwise the kit sorts the page it has and says that.
139  const sortedOnPage = query.sort !== undefined && list.sorted === undefined;
140  if (sortedOnPage) {
141    const natural = query.sort === "name" ? "asc" : "desc";
142    const flip = (query.dir ?? natural) === natural ? 1 : -1;
143    items = [...items].sort((a, b) => flip * MEDIA_BY[query.sort!](a, b));
144  }
145  const rows = items.map((item) => ({ ...item, src: absolute(source.site.origin, item.url) }));
146  let detail: MediaData["detail"];
147  if (query.inspect) {
148    const found = await orNull(source.client.media.get(query.inspect));
149    detail = found ? { ...found, src: absolute(source.site.origin, found.url) } : null;
150  }
151  const page = { nextCursor: list.nextCursor, ...(list.total !== undefined ? { total: list.total } : {}), ...(sortedOnPage ? { sortedOnPage } : {}) };
152  return { ...base, rows, page, ...(detail !== undefined ? { detail } : {}) };
153}
154
155const MEDIA_INTENTS = ["upload", "alt", "tags", "tag-add", "tag-remove", "trash", "restore", "delete", "empty-trash"] as const;
156export type MediaIntent = (typeof MEDIA_INTENTS)[number];
157
158/** A typed list of tags (commas between them) as a tag set: each in the site's spelling, unique, at most 12. */
159export function parseMediaTags(raw: string | string[]): { ok: true; tags: string[] } | { ok: false; message: string } {
160  const tags: string[] = [];
161  for (const part of (Array.isArray(raw) ? raw : [raw]).flatMap((r) => r.split(/[,\n]+/))) {
162    if (part.trim() === "") continue;
163    const tag = part.trim().toLowerCase().replace(/[\s_]+/g, "-");
164    if (!MediaTag.safeParse(tag).success) {
165      return { ok: false, message: `"${part.trim()}" cannot be a tag. A tag is lower case words and numbers joined by hyphens, up to 32 characters.` };
166    }
167    if (!tags.includes(tag)) tags.push(tag);
168  }
169  if (tags.length > 12) return { ok: false, message: "A file carries at most 12 tags." };
170  return { ok: true, tags };
171}
172
173function megabytes(bytes: number): string {
174  return bytes >= 1024 * 1024 ? `${(bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, "")} MB` : `${Math.ceil(bytes / 1024)} KB`;
175}
176
177/** The most rounds one empty-trash intent sends; each round deletes up to the site's limit. */
178const EMPTY_ROUNDS = 20;
179
180/**
181 * Runs one posted intent on one site's media library. Bulk intents go to the site as one bulk
182 * request; the site answers file by file, and every file gets an outcome.
183 */
184export async function runMediaIntent(source: ContentSource, input: IntentInput): Promise<IntentResult> {
185  const intent = text(input, "intent") as MediaIntent;
186  if (!MEDIA_INTENTS.includes(intent)) return refused("That is not something the media library can do.");
187  const need: keyof Permissions = intent === "delete" || intent === "empty-trash" ? "deleteMedia" : "edit";
188  if (!source.can[need]) return refused(NOT_YOURS[need]);
189  const offers = mediaOffers((await source.client.meta()).capabilities);
190  if (!offers.media) return refused("This site has no media library.");
191  const lacking =
192    (intent === "alt" && !offers.alt) ||
193    ((intent === "tags" || intent === "tag-add" || intent === "tag-remove") && !offers.tags) ||
194    ((intent === "trash" || intent === "restore" || intent === "empty-trash") && !offers.trash);
195  if (lacking) return refused("This site does not offer that.");
196
197  if (intent === "upload") return uploadOne(source, input, offers.upload!);
198  if (intent === "empty-trash") return emptyTrash(source);
199
200  const { targets, invalid } = targetsOf(input, MediaId);
201  const tooMany = checkCount(targets.length + invalid.length, "file");
202  if (tooMany) return tooMany;
203  const early: Outcome[] = invalid.map((id) => ({ id, ok: false, message: "That is not a file id, so it was not sent to the site." }));
204  // A write needs the version the person saw; without one the site could not tell a stale write from a fresh one.
205  const sendable = targets.filter((t) => intent === "delete" || t.version !== null);
206  for (const t of targets) {
207    if (!sendable.includes(t)) early.push({ id: t.id, ok: false, message: "The page did not say which version of this file you saw, so nothing was sent. Reload and try again." });
208  }
209
210  if (intent === "alt" || intent === "tags") {
211    if (sendable.length !== 1 || targets.length !== 1) return result(early, "Choose one file.");
212    const file = { id: sendable[0]!.id, version: sendable[0]!.version! };
213    return intent === "alt" ? setAlt(source, file, text(input, "alt")) : setFileTags(source, file, texts(input, "tags"));
214  }
215
216  let tags: string[] = [];
217  if (intent === "tag-add" || intent === "tag-remove") {
218    const parsed = parseMediaTags(texts(input, "tags"));
219    if (!parsed.ok) return refused(parsed.message);
220    if (parsed.tags.length === 0) return refused("Name at least one tag.");
221    tags = parsed.tags;
222  }
223
224  // Each file is read first where the kit needs what the site holds: which tags would really change
225  // (so Undo touches only those), and, on a site with a trash, that a delete is from the trash.
226  const before = new Map<string, MediaDetail>();
227  const plan: Array<{ id: string; version: string | null }> = [];
228  const { outcomes: checks, conflict: staleRead } = await eachItem(source, sendable, "file", async (t): Promise<Outcome> => {
229    if (intent === "tag-add" || intent === "tag-remove" || (intent === "delete" && offers.trash)) {
230      const detail = await source.client.media.get(t.id);
231      if (t.version !== null && detail.version !== t.version) throw new Conflict(detail.version ?? null);
232      before.set(t.id, detail);
233      if (intent === "delete" && !detail.trashedAt) {
234        return { id: t.id, ok: false, message: "Move this file to the trash first: files are deleted for good only from the trash." };
235      }
236      if (intent === "tag-add" || intent === "tag-remove") {
237        const held = detail.tags ?? [];
238        const changes = intent === "tag-add" ? tags.some((g) => !held.includes(g)) : tags.some((g) => held.includes(g));
239        if (!changes) return { id: t.id, ok: true, message: intent === "tag-add" ? "Already had those tags. Not changed." : "Had none of those tags. Not changed." };
240      }
241    }
242    plan.push(t);
243    return { id: t.id, ok: true, message: "" };
244  });
245  const settled = checks.filter((c) => !c.ok || c.message !== "");
246  const all: Outcome[] = [...early, ...settled];
247  if (plan.length === 0) return result(all, summarise(all, MEDIA_DONE[intent], "file"), staleRead ? { conflict: staleRead } : {});
248
249  const op = intent === "tag-add" ? "add-tags" : intent === "tag-remove" ? "remove-tags" : intent;
250  const sent = plan.map((p) => ({ ...p, changeId: changeId() }));
251  const answer = await source.client.media.bulk({
252    op,
253    ...(tags.length > 0 ? { tags } : {}),
254    items: sent.map((s) => ({ id: s.id, changeId: s.changeId, ...(op !== "delete" && s.version ? { expectedVersion: s.version } : {}) })),
255  });
256  const undoIds: string[] = [];
257  const undoVersions: string[] = [];
258  const undoTags = new Set<string>();
259  let conflict: IntentResult["conflict"] = staleRead;
260  for (const outcome of answer.results) {
261    if (outcome.ok) {
262      const note = await recordDone(source, `media-${intent}`, outcome.id, outcome.changeId);
263      all.push({ id: outcome.id, ok: true, message: MEDIA_DONE_ONE[intent] + note });
264      if (outcome.version) {
265        undoIds.push(outcome.id);
266        undoVersions.push(outcome.version);
267        const held = before.get(outcome.id)?.tags ?? [];
268        for (const g of tags) if (intent === "tag-add" ? !held.includes(g) : held.includes(g)) undoTags.add(`${outcome.id}\u0000${g}`);
269      }
270    } else {
271      if (outcome.error === "version-conflict" && !conflict) conflict = { id: outcome.id, currentVersion: outcome.currentVersion ?? null };
272      all.push({
273        id: outcome.id,
274        ok: false,
275        message: outcome.error === "version-conflict" ? "This file changed on the site since the page loaded. It was left as it was." : outcome.message,
276        ...(outcome.usedBy && outcome.usedBy.length > 0 ? { usedBy: outcome.usedBy } : {}),
277      });
278    }
279  }
280  const extra: Partial<IntentResult> = conflict ? { conflict } : {};
281  let tail = "";
282  if (undoIds.length > 0 && (intent === "trash" || intent === "restore")) {
283    extra.undo = { intent: intent === "trash" ? "restore" : "trash", fields: { ids: undoIds, versions: undoVersions } };
284  } else if (undoIds.length > 0 && (intent === "tag-add" || intent === "tag-remove")) {
285    // Undo applies the inverse to the files that changed, and only those: one bulk request when every
286    // file changed by the same tags, which a single tag always does.
287    const changed = undoIds.map((id) => tags.filter((g) => undoTags.has(`${id}\u0000${g}`)).join(","));
288    if (changed.every((c) => c === changed[0])) {
289      extra.undo = { intent: intent === "tag-add" ? "tag-remove" : "tag-add", fields: { ids: undoIds, versions: undoVersions, tags: changed[0]!.split(",") } };
290    } else tail = " The files changed by different tags, so there is no single Undo; change them one at a time to reverse it.";
291  }
292  return result(all, summarise(all, MEDIA_DONE[intent], "file") + tail, extra);
293}
294
295const MEDIA_DONE: Record<MediaIntent, string> = {
296  upload: "Uploaded",
297  alt: "Saved alt text on",
298  tags: "Saved tags on",
299  "tag-add": "Tagged",
300  "tag-remove": "Untagged",
301  trash: "Moved to the trash",
302  restore: "Restored",
303  delete: "Deleted",
304  "empty-trash": "Deleted",
305};
306
307const MEDIA_DONE_ONE: Record<MediaIntent, string> = {
308  upload: "Uploaded.",
309  alt: "Alt text saved.",
310  tags: "Tags saved.",
311  "tag-add": "Tags added.",
312  "tag-remove": "Tags removed.",
313  trash: "Moved to the trash.",
314  restore: "Restored to the library.",
315  delete: "Deleted from the site.",
316  "empty-trash": "Deleted from the site.",
317};
318
319/**
320 * Uploads one file. The kit checks the site's own limits first, so a file the site would refuse is
321 * not sent at all; the site API checks them again, and the bytes, before the site's code.
322 */
323async function uploadOne(source: ContentSource, input: IntentInput, limits: MediaUploadLimits): Promise<IntentResult> {
324  const file = fieldOf(input, "file").find((v): v is Blob => typeof v !== "string");
325  if (!file) return refused("Choose a file to upload.");
326  const name = (file as Blob & { name?: string }).name || "upload";
327  const type = file.type.split(";")[0]!.trim().toLowerCase();
328  if (!limits.types.includes(type)) {
329    return refused(`${name} is ${type || "an unknown type"}; this site accepts ${limits.types.map((t) => t.split("/")[1]).join(", ")}.`);
330  }
331  if (file.size > limits.maxBytes) return refused(`${name} is ${megabytes(file.size)}; this site accepts files up to ${megabytes(limits.maxBytes)}.`);
332  if (file.size === 0) return refused(`${name} is empty.`);
333  const change = changeId();
334  try {
335    const item = await source.client.media.upload({
336      bytes: new Uint8Array(await file.arrayBuffer()),
337      contentType: type,
338      filename: name.replace(/[/\\]/g, "-").slice(0, 200),
339      alt: text(input, "alt").trim().slice(0, 2000),
340      changeId: change,
341    });
342    const note = await recordDone(source, "media-upload", item.id, change);
343    return result([{ id: item.id, ok: true, message: "Uploaded." + note }], `Uploaded ${name}.` + note);
344  } catch (error) {
345    if (error instanceof SiteApiError && error.body) return refused(`The site refused ${name}: ${error.body.message}`);
346    throw error;
347  }
348}
349
350async function setAlt(source: ContentSource, file: { id: string; version: string }, alt: string): Promise<IntentResult> {
351  const { outcomes, conflict } = await eachItem(source, [file], "file", async ({ id, version }) => {
352    const change = changeId();
353    await source.client.media.setAlt(id, { alt: alt.trim().slice(0, 2000), expectedVersion: version, changeId: change });
354    return { id, ok: true, message: "Alt text saved." + (await recordDone(source, "media-alt", id, change)) };
355  });
356  return result(outcomes, outcomes[0]!.message, conflict ? { conflict } : {});
357}
358
359/** Sets a file's whole tag set. Undo sets back the set it held, at the version this write made. */
360async function setFileTags(source: ContentSource, file: { id: string; version: string }, raw: string[]): Promise<IntentResult> {
361  const parsed = parseMediaTags(raw);
362  if (!parsed.ok) return refused(parsed.message);
363  let undo: IntentResult["undo"];
364  const { outcomes, conflict } = await eachItem(source, [file], "file", async ({ id, version }) => {
365    const detail = await source.client.media.get(id);
366    if (detail.version !== version) throw new Conflict(detail.version ?? null);
367    const change = changeId();
368    const written = await source.client.media.setTags(id, { tags: parsed.tags, expectedVersion: version, changeId: change });
369    undo = { intent: "tags", fields: { ids: [id], versions: [written.version], tags: (detail.tags ?? []).join(", ") } };
370    return { id, ok: true, message: "Tags saved." + (await recordDone(source, "media-tags", id, change)) };
371  });
372  return result(outcomes, outcomes[0]!.message, { ...(conflict ? { conflict } : {}), ...(undo ? { undo } : {}) });
373}
374
375/**
376 * Deletes for good every file in the trash, each through the site's own reference check: a file a
377 * post still uses is refused and stays in the trash. Sends again while the site says more remain and
378 * the last round deleted something.
379 */
380async function emptyTrash(source: ContentSource): Promise<IntentResult> {
381  const outcomes: Outcome[] = [];
382  const refusedIds = new Set<string>();
383  let more = false;
384  for (let round = 0; round < EMPTY_ROUNDS; round++) {
385    // The site records file n under `<change id>-<n>` in the order it lists the trash, refused files
386    // included, so the kit lists the same trash first to record the same ids.
387    const order = source.record ? (await source.client.media.list({ trashed: "only", limit: 200 })).items.map((i) => i.id) : [];
388    const change = changeId();
389    const answer = await source.client.media.emptyTrash({ changeId: change });
390    for (const id of answer.deleted) {
391      const n = order.indexOf(id);
392      const note = await recordDone(source, "media-delete", id, n >= 0 ? `${change}-${n + 1}` : `${change}:${id}`);
393      outcomes.push({ id, ok: true, message: "Deleted from the site." + note });
394    }
395    for (const r of answer.refused) {
396      if (refusedIds.has(r.id)) continue;
397      refusedIds.add(r.id);
398      outcomes.push({ id: r.id, ok: false, message: r.message, ...(r.usedBy && r.usedBy.length > 0 ? { usedBy: r.usedBy } : {}) });
399    }
400    more = answer.more;
401    if (!answer.more || answer.deleted.length === 0) break;
402  }
403  if (outcomes.length === 0) return { ok: true, message: "The trash was already empty.", outcomes };
404  const deleted = outcomes.filter((o) => o.ok).length;
405  const kept = outcomes.length - deleted;
406  const message =
407    `Deleted ${plural(deleted, "file")} from the trash for good.` +
408    (kept > 0 ? ` ${plural(kept, "file")} ${kept === 1 ? "is" : "are"} still used and stayed in the trash.` : "") +
409    (more ? " More remain; empty the trash again." : "");
410  return { ok: kept === 0 && !more, message, outcomes };
411}