src/admin/kit.ts

Functions

Imports

It imports src/client.ts, src/contract.ts. Imported by src/admin.ts, src/admin/media.ts, src/admin/mentions.ts, src/admin/posts.ts, src/admin/summary.ts.

Source

1// What the host supplies, what an intent returns, and the plumbing the posts, media and mentions halves share.
2
3import { SiteApiError, type SiteClient } from "../client.js";
4import { Version, type ContentList, type ListQuery, type MediaUse } from "../contract.js";
5
6// ---------- what the host supplies
7
8/** What this person may do on this site. The kit refuses an intent the person may not run, whatever the form says. */
9export interface Permissions {
10  /** Tag, duplicate, upload, edit alt text and tags, trash and restore. */
11  edit: boolean;
12  /** Change what the public sees: unpublish, republish, and any write to a post that is not a draft. */
13  publish: boolean;
14  deleteContent: boolean;
15  deleteMedia: boolean;
16  decideMentions: boolean;
17}
18
19/** A host-supplied fact about one row, such as "2 AI drafts waiting" or "New draft". */
20export interface RowNote {
21  text: string;
22  tone?: "info" | "warning";
23}
24
25export interface ContentSource {
26  site: { id: string; name: string; origin: string };
27  /** createSiteClient({ baseUrl, key }) in Carrel; localClient(adapter) in a site's own admin. */
28  client: SiteClient;
29  can: Permissions;
30  /** Where a row's title links: Carrel's editor, or the site's own. */
31  editorHref(id: string): string;
32  /** Optional: a faster list than the site's own, such as Carrel's search index. Same answer as client.list. */
33  postIndex?: { list(query: Partial<ListQuery> & { limit: number }): Promise<ContentList> };
34  /** Optional: notes per post id, for the rows on this page. */
35  notes?(ids: string[]): Promise<Record<string, RowNote[]>>;
36  /** Optional: how many posts the host has something waiting on (Carrel's AI drafts), for summary(). */
37  waiting?(): Promise<number>;
38  /** Optional: a host reason to leave one post alone, such as Carrel's unsaved working draft of it. null lets it go on. */
39  hold?(intent: string, id: string): Promise<string | null>;
40  /** Optional: true for an id the host already uses that the site does not know yet, so a copy never takes it. */
41  taken?(id: string): Promise<boolean>;
42  /** Optional: records who did what. Called once per item the site carried out, with the change id sent for it. */
43  record?(change: { kind: string; ids: string[]; changeId: string }): Promise<void>;
44  /** Where unexpected failures are logged. Defaults to console.error. */
45  log?(entry: Record<string, unknown>): void;
46}
47
48// ---------- what an intent returns
49
50/** The fields a form posts. A list (ids, versions) is an array; one value is a string. An upload's file is a Blob. */
51export type Fields = Record<string, string | string[]>;
52export type IntentInput = FormData | Record<string, string | string[] | Blob>;
53
54export interface Outcome {
55  id: string;
56  ok: boolean;
57  message: string;
58  usedBy?: MediaUse[];
59  /** The new copy's id, after a duplicate. */
60  copyId?: string;
61}
62
63export interface IntentResult {
64  ok: boolean;
65  /** One sentence for the message region. */
66  message: string;
67  outcomes?: Outcome[];
68  /** The inverse, as the fields to post with it, versions included. Absent when the action cannot be undone. */
69  undo?: { intent: string; fields: Fields };
70  /** Set when one item changed on the site since the person saw it. */
71  conflict?: { id: string; currentVersion: string | null };
72}
73
74/** The most items one intent acts on, as the site's own bulk route allows. */
75const MAX_INTENT_ITEMS = 100;
76export const PER_PAGE = 50;
77
78// ---------- shared plumbing
79
80export function fieldOf(input: IntentInput, name: string): Array<string | Blob> {
81  if (input instanceof FormData) return input.getAll(name) as Array<string | Blob>;
82  const value = input[name];
83  return value === undefined ? [] : Array.isArray(value) ? value : [value];
84}
85
86export function texts(input: IntentInput, name: string): string[] {
87  return fieldOf(input, name).filter((v): v is string => typeof v === "string");
88}
89
90export function text(input: IntentInput, name: string): string {
91  return texts(input, name)[0] ?? "";
92}
93
94export function refused(message: string): IntentResult {
95  return { ok: false, message };
96}
97
98export function plural(n: number, one: string, many = `${one}s`): string {
99  return `${n} ${n === 1 ? one : many}`;
100}
101
102export function changeId(): string {
103  return crypto.randomUUID();
104}
105
106function logOf(source: ContentSource) {
107  return (entry: Record<string, unknown>) => (source.log ? source.log(entry) : console.error(JSON.stringify(entry)));
108}
109
110/** Records one done item. A record that cannot be written is said in the outcome, never hidden. */
111export async function recordDone(source: ContentSource, kind: string, id: string, change: string): Promise<string> {
112  if (!source.record) return "";
113  try {
114    await source.record({ kind, ids: [id], changeId: change });
115    return "";
116  } catch (error) {
117    logOf(source)({ contentKit: "record-failed", kind, id, changeId: change, error: String(error) });
118    return " The record of it could not be saved.";
119  }
120}
121
122/**
123 * The ids and their versions, as the form sent them: `ids` and, when the person saw them, `versions`
124 * in the same order. Unique, each shaped as the site could hold it; anything else is reported, not sent.
125 */
126export function targetsOf(
127  input: IntentInput,
128  shape: { safeParse(v: unknown): { success: boolean } },
129): { targets: Array<{ id: string; version: string | null; status: string | null }>; invalid: string[] } {
130  const ids = texts(input, "ids");
131  const versions = texts(input, "versions");
132  const statuses = texts(input, "statuses");
133  const targets: Array<{ id: string; version: string | null; status: string | null }> = [];
134  const invalid: string[] = [];
135  const seen = new Set<string>();
136  ids.forEach((id, i) => {
137    if (seen.has(id)) return;
138    seen.add(id);
139    const version = versions[i] ?? "";
140    if (!shape.safeParse(id).success || (version !== "" && !Version.safeParse(version).success)) invalid.push(id || "(no id)");
141    else targets.push({ id, version: version === "" ? null : version, status: statuses[i] || null });
142  });
143  return { targets, invalid };
144}
145
146export function checkCount(total: number, noun: string): IntentResult | null {
147  if (total === 0) return refused(`Choose at least one ${noun}.`);
148  if (total > MAX_INTENT_ITEMS) return refused(`At most ${MAX_INTENT_ITEMS} ${noun}s at a time.`);
149  return null;
150}
151
152/** The message for a whole run: what was done, and how many were left as they were. */
153export function summarise(outcomes: Outcome[], done: string, noun: string): string {
154  const ok = outcomes.filter((o) => o.ok).length;
155  const left = outcomes.length - ok;
156  if (left === 0) return `${done} ${plural(ok, noun)}.`;
157  if (ok === 0) return `Nothing was changed: ${plural(left, noun)} left as ${left === 1 ? "it was" : "they were"}.`;
158  return `${done} ${plural(ok, noun)}; ${left} left as ${left === 1 ? "it was" : "they were"}.`;
159}
160
161export function result(outcomes: Outcome[], message: string, extra: Partial<IntentResult> = {}): IntentResult {
162  return { ok: outcomes.length > 0 && outcomes.every((o) => o.ok), message, outcomes, ...extra };
163}
164
165/** A 404 from the site, as null; anything else is the caller's to handle. */
166export async function orNull<T>(read: Promise<T>): Promise<T | null> {
167  try {
168    return await read;
169  } catch (error) {
170    if (error instanceof SiteApiError && (error.status === 404 || error.status === 400)) return null;
171    throw error;
172  }
173}
174
175export class Conflict extends Error {
176  constructor(readonly currentVersion: string | null) {
177    super("conflict");
178  }
179}
180
181/** What went wrong for one item, said plainly. Anything unexpected is logged and reported, never dropped. */
182export function failure(source: ContentSource, id: string, error: unknown, noun: string): Outcome & { currentVersion?: string | null } {
183  if (error instanceof Conflict) {
184    return { id, ok: false, message: `This ${noun} changed on the site since the page loaded. It was left as it was.`, currentVersion: error.currentVersion };
185  }
186  if (error instanceof SiteApiError) {
187    if (error.body?.error === "version-conflict") {
188      return { id, ok: false, message: `This ${noun} changed on the site since the page loaded. It was left as it was.`, currentVersion: error.body.currentVersion ?? null };
189    }
190    if (error.status === 404) return { id, ok: false, message: `The site does not have this ${noun}. It may have been deleted.` };
191    if (error.status === 501) return { id, ok: false, message: "This site does not offer that." };
192    if (error.body?.error === "refused") return { id, ok: false, message: error.body.message, ...(error.body.usedBy ? { usedBy: error.body.usedBy } : {}) };
193  }
194  logOf(source)({ contentKit: "item-failed", id, error: error instanceof SiteApiError ? `site ${error.status} ${error.body?.error ?? ""}` : String(error) });
195  return { id, ok: false, message: `The site did not accept this change. The ${noun} was left as it was.` };
196}
197
198/** Runs each item in order. One failing never stops the rest; the first conflict is named on the result. */
199export async function eachItem<T extends { id: string }>(
200  source: ContentSource,
201  items: T[],
202  noun: string,
203  run: (item: T) => Promise<Outcome>,
204): Promise<{ outcomes: Outcome[]; conflict?: { id: string; currentVersion: string | null } }> {
205  const outcomes: Outcome[] = [];
206  let conflict: { id: string; currentVersion: string | null } | undefined;
207  for (const item of items) {
208    try {
209      outcomes.push(await run(item));
210    } catch (error) {
211      const { currentVersion, ...outcome } = failure(source, item.id, error, noun);
212      if (currentVersion !== undefined && !conflict) conflict = { id: item.id, currentVersion };
213      outcomes.push(outcome);
214    }
215  }
216  return { outcomes, ...(conflict ? { conflict } : {}) };
217}
218
219export function absolute(origin: string, url: string): string {
220  return url.startsWith("/") ? `${origin.replace(/\/+$/, "")}${url}` : url;
221}
222
223export const NOT_YOURS: Record<keyof Permissions, string> = {
224  edit: "You may not change posts on this site.",
225  publish: "Changing what the public sees is not yours to do on this site.",
226  deleteContent: "Deleting a post is the Owner's step.",
227  deleteMedia: "Deleting a file for good is the Owner's step.",
228  decideMentions: "Deciding mentions is not yours to do on this site.",
229};