src/admin/posts.ts

Functions

Imports

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

Source

1// The posts half of the content kit: PostsList's view data and its intents.
2
3import { SiteApiError } from "../client.js";
4import {
5  ContentId,
6  ContentTag,
7  type Capabilities,
8  type ContentDoc,
9  type ContentStatus,
10  type ContentSummary,
11  type SortDir,
12} from "../contract.js";
13import { joinSource, readKey, setRawKey, setTags, splitSource, tagsOf } from "../frontmatter.js";
14import {
15  type Permissions,
16  type ContentSource,
17  type RowNote,
18  type IntentInput,
19  type Outcome,
20  type IntentResult,
21  PER_PAGE,
22  NOT_YOURS,
23  text,
24  refused,
25  changeId,
26  recordDone,
27  targetsOf,
28  checkCount,
29  summarise,
30  result,
31  orNull,
32  Conflict,
33  eachItem,
34  absolute,
35} from "./kit.js";
36
37
38export type PostSort = "updated" | "published" | "title";
39const POST_SORTS: readonly PostSort[] = ["updated", "published", "title"];
40
41export interface PostQuery {
42  q?: string;
43  status?: ContentStatus;
44  kind?: string;
45  tag?: string;
46  sort?: PostSort;
47  dir?: SortDir;
48  cursor?: string;
49}
50
51export interface PostRow {
52  id: string;
53  title: string;
54  kind: string;
55  status: ContentStatus;
56  path: string | null;
57  href: string;
58  liveHref: string | null;
59  publishAt: string | null;
60  publishedAt: string | null;
61  updatedAt: string | null;
62  /** Present when the site's list carries it. */
63  version?: string;
64  tags?: string[];
65  notes?: RowNote[];
66}
67
68export interface PostsData {
69  site: { id: string; name: string };
70  query: PostQuery;
71  rows: PostRow[];
72  page: {
73    nextCursor: string | null;
74    total?: number;
75    /** True when the rows were sorted on this page only, because the site's list does not sort. */
76    sortedOnPage?: boolean;
77  };
78  counts?: Partial<Record<ContentStatus | "all", number>>;
79  kinds: string[];
80  offers: { delete: boolean; schedule: boolean; tags: boolean; duplicate: boolean };
81  can: Permissions;
82}
83
84/** A posts query from the address: anything the kit does not know is dropped, never sent. */
85export function readPostQuery(search: URLSearchParams): PostQuery {
86  const q = search.get("q")?.trim().slice(0, 200);
87  const status = search.get("status");
88  const kind = search.get("kind")?.trim().slice(0, 64);
89  const tag = search.get("tag")?.trim().slice(0, 40);
90  const sort = search.get("sort");
91  const dir = search.get("dir");
92  const cursor = search.get("cursor")?.slice(0, 500);
93  return {
94    ...(dir === "asc" || dir === "desc" ? { dir } : {}),
95    ...(q ? { q } : {}),
96    ...(status && (["draft", "scheduled", "published"] as const).includes(status as ContentStatus) ? { status: status as ContentStatus } : {}),
97    ...(kind ? { kind } : {}),
98    ...(tag ? { tag } : {}),
99    ...(sort && POST_SORTS.includes(sort as PostSort) ? { sort: sort as PostSort } : {}),
100    ...(cursor ? { cursor } : {}),
101  };
102}
103
104function postRow(source: ContentSource, item: ContentSummary & { version?: string; tags?: string[] }): PostRow {
105  return {
106    id: item.id,
107    title: item.title || item.id,
108    kind: item.kind,
109    status: item.status,
110    path: item.path,
111    href: source.editorHref(item.id),
112    liveHref: item.status === "published" && item.path ? absolute(source.site.origin, item.path) : null,
113    publishAt: item.publishAt,
114    publishedAt: item.publishedAt,
115    updatedAt: item.updatedAt,
116    ...(item.version ? { version: item.version } : {}),
117    ...(item.tags ? { tags: item.tags } : {}),
118  };
119}
120
121const BY: Record<PostSort, (a: PostRow, b: PostRow) => number> = {
122  updated: (a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""),
123  published: (a, b) => (b.publishedAt ?? b.publishAt ?? "").localeCompare(a.publishedAt ?? a.publishAt ?? ""),
124  title: (a, b) => a.title.localeCompare(b.title),
125};
126
127/** One page of one site's posts, as PostsList renders it. */
128export async function loadPosts(source: ContentSource, query: PostQuery = {}): Promise<PostsData> {
129  const meta = await source.client.meta();
130  const lister = source.postIndex ?? source.client;
131  const base = { ...(query.q ? { q: query.q } : {}), ...(query.sort ? { sort: query.sort, ...(query.dir ? { dir: query.dir } : {}) } : {}) };
132  const list = await lister.list({ limit: PER_PAGE, ...base, ...(query.status ? { status: query.status } : {}), ...(query.cursor ? { cursor: query.cursor } : {}) });
133  let rows = list.items.map((item) => postRow(source, item));
134  const kinds = [...new Set(rows.map((r) => r.kind))].sort();
135  // The contract has no kind or tag filter, so these work on the page the site sent.
136  if (query.kind) rows = rows.filter((r) => r.kind === query.kind);
137  if (query.tag) rows = rows.filter((r) => (r.tags ?? []).some((t) => sameTag(t, query.tag!)));
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 dir = query.dir ?? (query.sort === "title" ? "asc" : "desc");
142    rows = [...rows].sort((a, b) => (dir === (query.sort === "title" ? "asc" : "desc") ? 1 : -1) * BY[query.sort!](a, b));
143  }
144  // Where the site counts (v0.6.0), each status tab gets its count for the same search.
145  let counts: PostsData["counts"];
146  if (list.total !== undefined) {
147    const statuses = ["draft", "scheduled", "published"] as const;
148    const totals = await Promise.all(statuses.map((status) => lister.list({ limit: 1, ...(query.q ? { q: query.q } : {}), status })));
149    counts = { all: query.status ? totals.reduce((n, t) => n + (t.total ?? 0), 0) : list.total };
150    statuses.forEach((status, i) => (counts![status] = totals[i]!.total ?? 0));
151  }
152  if (source.notes && rows.length > 0) {
153    const notes = await source.notes(rows.map((r) => r.id));
154    rows = rows.map((r) => (notes[r.id]?.length ? { ...r, notes: notes[r.id] } : r));
155  }
156  return {
157    site: { id: source.site.id, name: source.site.name },
158    query,
159    rows,
160    page: { nextCursor: list.nextCursor, ...(list.total !== undefined ? { total: list.total } : {}), ...(sortedOnPage ? { sortedOnPage } : {}) },
161    ...(counts ? { counts } : {}),
162    kinds,
163    offers: { delete: meta.capabilities.contentDelete === true, schedule: true, tags: true, duplicate: true },
164    can: source.can,
165  };
166}
167
168const POST_INTENTS = ["tag-add", "tag-remove", "duplicate", "unpublish", "republish", "delete"] as const;
169export type PostIntent = (typeof POST_INTENTS)[number];
170
171/** A tag as a post's frontmatter list can hold it: one short piece of text with nothing that would break the list. */
172function cleanPostTag(raw: string): string | null {
173  const tag = raw.trim();
174  return ContentTag.safeParse(tag).success ? tag : null;
175}
176
177const sameTag = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
178
179const COPY_TRIES = 50;
180
181/**
182 * Runs one posted intent on one site's posts, each post its own write, in order. The person's
183 * permission is checked once before the site is asked anything; a post whose own state needs more
184 * (a live post, for someone who may not publish) is refused alone and the rest go on.
185 */
186export async function runPostsIntent(source: ContentSource, input: IntentInput): Promise<IntentResult> {
187  const intent = text(input, "intent") as PostIntent;
188  if (!POST_INTENTS.includes(intent)) return refused("That is not something the posts list can do.");
189  const need: keyof Permissions = intent === "delete" ? "deleteContent" : intent === "unpublish" || intent === "republish" ? "publish" : "edit";
190  if (!source.can[need]) return refused(NOT_YOURS[need]);
191
192  const { targets, invalid } = targetsOf(input, ContentId);
193  const tooMany = checkCount(targets.length + invalid.length, "post");
194  if (tooMany) return tooMany;
195  const early: Outcome[] = invalid.map((id) => ({ id, ok: false, message: "That is not a post id, so it was not sent to the site." }));
196
197  let tag: string | null = null;
198  if (intent === "tag-add" || intent === "tag-remove") {
199    tag = cleanPostTag(text(input, "tag"));
200    if (tag === null) return refused("A tag is one short piece of text, with no commas, brackets, quotes or colons.");
201  }
202  let capabilities: Capabilities | null = null;
203  if (intent !== "unpublish" && intent !== "republish") capabilities = (await source.client.meta()).capabilities;
204  if (intent === "delete" && capabilities?.contentDelete !== true) return refused("This site does not delete posts through the site API.");
205
206  const client = source.client;
207  const read = async (id: string, version: string | null): Promise<ContentDoc> => {
208    const doc = await client.get(id);
209    if (version !== null && doc.version !== version) throw new Conflict(doc.version);
210    return doc;
211  };
212  const held = async (id: string): Promise<string | null> => (source.hold ? source.hold(intent, id) : null);
213  const undoIds: string[] = [];
214  const undoVersions: string[] = [];
215  let notUndoable = 0;
216
217  const { outcomes, conflict } = await eachItem(source, targets, "post", async ({ id, version }): Promise<Outcome> => {
218    const hold = await held(id);
219    if (hold) return { id, ok: false, message: hold };
220    switch (intent) {
221      case "tag-add":
222      case "tag-remove": {
223        const doc = await read(id, version);
224        if (doc.status !== "draft" && !source.can.publish) return { id, ok: false, message: LIVE_POST };
225        // A site that keeps tags (v0.6.0) writes them through its own route; otherwise the frontmatter is rewritten, as Carrel did.
226        const viaRoute = capabilities?.contentTags === true;
227        const parts = splitSource(doc.source);
228        if (!viaRoute && parts.front === null) return { id, ok: false, message: "This post has no frontmatter, so it has no tags to change." };
229        const tags = viaRoute ? (doc.tags ?? []) : tagsOf(parts.front);
230        const has = tags.some((t) => sameTag(t, tag!));
231        if (intent === "tag-add" && has) return { id, ok: true, message: `Already tagged "${tag}". Not changed.` };
232        if (intent === "tag-remove" && !has) return { id, ok: true, message: `Did not have the tag "${tag}". Not changed.` };
233        const next = intent === "tag-add" ? [...tags, tag!] : tags.filter((t) => !sameTag(t, tag!));
234        const change = changeId();
235        const written = viaRoute
236          ? await client.setTags(id, { tags: next, expectedVersion: doc.version, changeId: change })
237          : await client.saveDraft(id, { source: joinSource({ ...parts, front: setTags(parts.front!, next) }), expectedVersion: doc.version, changeId: change });
238        undoIds.push(id);
239        undoVersions.push(written.version);
240        const note = await recordDone(source, `post-${intent}`, id, change);
241        return { id, ok: true, message: (intent === "tag-add" ? `Added the tag "${tag}".` : `Removed the tag "${tag}".`) + note };
242      }
243      case "duplicate": {
244        const doc = await read(id, version);
245        const parts = splitSource(doc.source);
246        if (parts.front === null) return { id, ok: false, message: "This post has no frontmatter, so it cannot be copied as a draft." };
247        const copy = await freeCopyId(source, id);
248        if (!copy) return { id, ok: false, message: "No unused id was found for the copy. Rename an earlier copy and try again." };
249        let front = setRawKey(parts.front, "title", JSON.stringify(`${readKey(parts.front, "title") || id} (copy${copy.n > 1 ? ` ${copy.n}` : ""})`));
250        // The site's own copy of the id sits in the file as well; a copy that kept the old one would clash with the original.
251        if (/^slug:/m.test(front)) front = setRawKey(front, "slug", copy.id);
252        front = setRawKey(front, "draft", "true");
253        const change = changeId();
254        let written;
255        try {
256          written = await client.saveDraft(copy.id, { source: joinSource({ ...parts, front }), expectedVersion: null, changeId: change });
257        } catch (error) {
258          if (error instanceof SiteApiError && error.body?.error === "version-conflict") {
259            return { id, ok: false, message: "The id chosen for the copy was taken while this ran. Nothing was copied." };
260          }
261          throw error;
262        }
263        undoIds.push(copy.id);
264        undoVersions.push(written.version);
265        const note = await recordDone(source, "post-duplicate", copy.id, change);
266        return { id, ok: true, message: `Copied as a draft with the id "${copy.id}".` + note, copyId: copy.id };
267      }
268      case "unpublish": {
269        const doc = await read(id, version);
270        if (doc.status === "draft") return { id, ok: true, message: "Not published, so there was nothing to unpublish." };
271        const change = changeId();
272        const written = await client.unpublish(id, { expectedVersion: doc.version, changeId: change });
273        // Undo republishes, so only a post that has been public before gets one: never a first publication.
274        if (doc.status === "published" && doc.publishedAt !== null) {
275          undoIds.push(id);
276          undoVersions.push(written.version);
277        } else notUndoable++;
278        const note = await recordDone(source, "post-unpublish", id, change);
279        return { id, ok: true, message: (doc.status === "scheduled" ? "Unscheduled; it is a draft again." : "Unpublished; it is a draft again.") + note };
280      }
281      case "republish": {
282        const doc = await read(id, version);
283        if (doc.status !== "draft") return { id, ok: true, message: "Already live. Not changed." };
284        if (doc.publishedAt === null) {
285          return { id, ok: false, message: "This post has never been published, so it was not published here. A first publication is made from the editor." };
286        }
287        const change = changeId();
288        const written = await client.publish(id, { expectedVersion: doc.version, changeId: change });
289        undoIds.push(id);
290        undoVersions.push(written.version);
291        const note = await recordDone(source, "post-republish", id, change);
292        return { id, ok: true, message: "Published again." + note };
293      }
294      case "delete": {
295        const doc = await read(id, version);
296        const change = changeId();
297        await client.delete(id, { expectedVersion: doc.version, changeId: change });
298        const note = await recordDone(source, "post-delete", id, change);
299        return { id, ok: true, message: "Deleted from the site." + note };
300      }
301    }
302  });
303
304  const all = [...early, ...outcomes];
305  const extra: Partial<IntentResult> = conflict ? { conflict } : {};
306  let tail = "";
307  if (undoIds.length > 0) {
308    const inverse = undoIntent(intent, capabilities, source.can);
309    if (inverse) extra.undo = { intent: inverse, fields: { ids: undoIds, versions: undoVersions, ...(tag ? { tag } : {}) } };
310    else if (intent === "duplicate") {
311      tail =
312        capabilities?.contentDelete === true
313          ? " Deleting a post is the Owner's step, so ask the Owner to remove a copy you do not want."
314          : " This site does not delete posts through the site API, so remove a copy you do not want in the site's own admin.";
315    }
316  }
317  if (notUndoable > 0) tail += ` A post that was only scheduled has no Undo; schedule it again from the editor.`;
318  return result(all, summarise(all, DONE[intent], "post") + tail, extra);
319}
320
321const DONE: Record<PostIntent, string> = {
322  "tag-add": "Tagged",
323  "tag-remove": "Untagged",
324  duplicate: "Copied",
325  unpublish: "Unpublished",
326  republish: "Republished",
327  delete: "Deleted",
328};
329
330const LIVE_POST = "Changing a live post is a publish, which is not yours to do here, so this one was left as it was.";
331
332/** The inverse of a posts intent, or null when it has none here. */
333function undoIntent(intent: PostIntent, capabilities: Capabilities | null, can: Permissions): string | null {
334  switch (intent) {
335    case "tag-add":
336      return "tag-remove";
337    case "tag-remove":
338      return "tag-add";
339    case "unpublish":
340      return "republish";
341    case "republish":
342      return "unpublish";
343    case "duplicate":
344      // Undo deletes the copy, at the version the duplicate made: only where the site deletes and the person may.
345      return capabilities?.contentDelete === true && can.deleteContent ? "delete" : null;
346    case "delete":
347      return null;
348  }
349}
350
351/** The first of id-copy, id-copy-2, ... that neither the site nor the host already uses. */
352async function freeCopyId(source: ContentSource, id: string): Promise<{ id: string; n: number } | null> {
353  for (let n = 1; n <= COPY_TRIES; n++) {
354    const candidate = n === 1 ? `${id}-copy` : `${id}-copy-${n}`;
355    if (!ContentId.safeParse(candidate).success) return null;
356    if (source.taken && (await source.taken(candidate))) continue;
357    if ((await orNull(source.client.get(candidate))) === null) return { id: candidate, n };
358  }
359  return null;
360}