src/admin/mentions.ts

Functions

Imports

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

Source

1// The mentions half of the content kit: MentionsList's view data and its intents.
2
3import {
4  MentionId,
5  MentionStatus,
6  type MentionCounts,
7  type MentionItem,
8  type MentionList,
9} from "../contract.js";
10import {
11  type Permissions,
12  type ContentSource,
13  type IntentInput,
14  type Outcome,
15  type IntentResult,
16  PER_PAGE,
17  NOT_YOURS,
18  text,
19  refused,
20  changeId,
21  recordDone,
22  targetsOf,
23  checkCount,
24  summarise,
25  result,
26  failure,
27  eachItem,
28} from "./kit.js";
29
30
31export type MentionFilter = MentionStatus | "all";
32export const MENTION_FILTERS: readonly MentionFilter[] = ["pending", "failed", "approved", "rejected", "unverified", "all"];
33
34export interface MentionsQuery {
35  /** Absent: open on pending, or on all when nothing is pending. */
36  status?: MentionFilter;
37  /** v0.6.0: words in the source, the author or the excerpt. */
38  q?: string;
39  /** v0.6.0: only the mentions of this post. */
40  targetId?: string;
41  cursor?: string;
42}
43
44export type MentionRow = MentionItem & { postHref: string };
45
46export interface MentionsData {
47  site: { id: string; name: string };
48  /** The filter shown, after the default was applied. */
49  filter: MentionFilter;
50  query: MentionsQuery;
51  rows: MentionRow[];
52  page: {
53    nextCursor: string | null;
54    /** True when q or targetId was applied to this page only, because the site's list does not filter by them. */
55    filteredOnPage?: boolean;
56  };
57  /** Across the whole queue, not the page. */
58  counts: MentionCounts;
59  /** What a sweep would remove now. */
60  expiring: MentionList["expiring"];
61  offers: { mentions: boolean; reset: boolean };
62  can: Permissions;
63}
64
65export function readMentionsQuery(search: URLSearchParams): MentionsQuery {
66  const status = search.get("status");
67  const cursor = search.get("cursor")?.slice(0, 500);
68  const q = search.get("q")?.trim().slice(0, 200);
69  const targetId = search.get("targetId")?.trim().slice(0, 300);
70  return {
71    ...(status && MENTION_FILTERS.includes(status as MentionFilter) ? { status: status as MentionFilter } : {}),
72    ...(q ? { q } : {}),
73    ...(targetId ? { targetId } : {}),
74    ...(cursor ? { cursor } : {}),
75  };
76}
77
78const NO_COUNTS: MentionCounts = { unverified: 0, pending: 0, approved: 0, rejected: 0, failed: 0 };
79
80/** One page of one site's mention queue, as MentionsList renders it. */
81export async function loadMentions(source: ContentSource, query: MentionsQuery = {}): Promise<MentionsData> {
82  const capabilities = (await source.client.meta()).capabilities;
83  const base = { site: { id: source.site.id, name: source.site.name }, query, can: source.can, offers: { mentions: capabilities.mentions === true, reset: capabilities.mentions === true && capabilities.mentionReset === true } };
84  if (capabilities.mentions !== true) {
85    return { ...base, filter: query.status ?? "all", rows: [], page: { nextCursor: null }, counts: NO_COUNTS, expiring: { failed: 0, rejected: 0 } };
86  }
87  const page = (filter: MentionFilter) =>
88    source.client.mentions.list({
89      limit: PER_PAGE,
90      ...(filter === "all" ? {} : { status: filter }),
91      ...(query.q ? { q: query.q } : {}),
92      ...(query.targetId ? { targetId: query.targetId } : {}),
93      ...(query.cursor ? { cursor: query.cursor } : {}),
94    });
95  let filter: MentionFilter = query.status ?? "pending";
96  let list = await page(filter);
97  if (!query.status && list.items.length === 0 && list.counts.pending === 0) {
98    filter = "all";
99    list = await page("all");
100  }
101  // A site that filtered echoes it (v0.6.0); otherwise the kit filters the page it has and says that.
102  let items = list.items;
103  const filteredOnPage = (query.q !== undefined || query.targetId !== undefined) && list.filtered === undefined;
104  if (filteredOnPage) {
105    const needle = query.q?.toLowerCase();
106    items = items.filter(
107      (m) =>
108        (!query.targetId || m.targetId === query.targetId) &&
109        (!needle || [m.sourceUrl, m.authorName ?? "", m.excerpt ?? ""].some((t) => t.toLowerCase().includes(needle))),
110    );
111  }
112  return {
113    ...base,
114    filter,
115    rows: items.map((m) => ({ ...m, postHref: source.editorHref(m.targetId) })),
116    page: { nextCursor: list.nextCursor, ...(filteredOnPage ? { filteredOnPage } : {}) },
117    counts: list.counts,
118    expiring: list.expiring,
119  };
120}
121
122const MENTION_INTENTS = ["approve", "reject", "reset", "delete", "sweep"] as const;
123export type MentionIntent = (typeof MENTION_INTENTS)[number];
124
125/** Said when the write moved but the site could not clear its cache. */
126const PURGE_FAILED = " The site could not clear its cache, so the post's page may show the old mentions until its cache expires.";
127
128/**
129 * Approves, rejects, resets (v0.6.0) or deletes each mention, in order, each with its own change id and record, or
130 * sweeps the queue. Each write carries the version the person saw, so a mention the site changed since
131 * is refused as stale and stays.
132 */
133export async function runMentionsIntent(source: ContentSource, input: IntentInput): Promise<IntentResult> {
134  const intent = text(input, "intent") as MentionIntent;
135  if (!MENTION_INTENTS.includes(intent)) return refused("That is not something the mentions list can do.");
136  if (!source.can.decideMentions) return refused(NOT_YOURS.decideMentions);
137  const capabilities = (await source.client.meta()).capabilities;
138  if (capabilities.mentions !== true) return refused("This site does not receive webmentions through the site API.");
139  const canReset = capabilities.mentionReset === true;
140  if (intent === "reset" && !canReset) return refused("This site does not take a mention decision back.");
141
142  if (intent === "sweep") {
143    const change = changeId();
144    try {
145      const { removed } = await source.client.mentions.sweep({ changeId: change });
146      const note = await recordDone(source, "mention-sweep", "sweep", change);
147      const n = removed.failed + removed.rejected;
148      return { ok: true, message: `Removed ${removed.failed} failed and ${removed.rejected} rejected mention${n === 1 ? "" : "s"} past their retention window.` + note };
149    } catch (error) {
150      return refused(failure(source, "sweep", error, "mention").message);
151    }
152  }
153
154  const { targets, invalid } = targetsOf(input, MentionId);
155  const tooMany = checkCount(targets.length + invalid.length, "mention");
156  if (tooMany) return tooMany;
157  const early: Outcome[] = invalid.map((id) => ({ id, ok: false, message: "That is not a mention id, so it was not sent to the site." }));
158  for (const t of targets) {
159    if (t.version === null) early.push({ id: t.id, ok: false, message: "The page did not say which version of this mention you saw, so nothing was sent. Reload and try again." });
160  }
161  const sendable = targets.filter((t): t is { id: string; version: string; status: string | null } => t.version !== null);
162
163  // Each done mention's inverse: the opposite decision between approved and rejected, a reset (v0.6.0)
164  // for a decision on a waiting mention, and the decision that was taken back for a reset.
165  const inverses: Array<{ id: string; version: string; intent: MentionIntent; status: MentionStatus }> = [];
166  let noUndo = 0;
167  const { outcomes, conflict } = await eachItem(source, sendable, "mention", async ({ id, version, status }): Promise<Outcome> => {
168    const change = changeId();
169    if (intent === "delete") {
170      const { purged } = await source.client.mentions.delete(id, { expectedVersion: version, changeId: change });
171      return { id, ok: true, message: "Deleted." + (purged === false ? PURGE_FAILED : "") + (await recordDone(source, "mention-delete", id, change)) };
172    }
173    const written = await source.client.mentions.decide(id, { decision: intent as "approve" | "reject" | "reset", expectedVersion: version, changeId: change });
174    const parsed = MentionStatus.safeParse(status);
175    const was = parsed.success ? parsed.data : null;
176    const inverse: MentionIntent | null =
177      was === written.status
178        ? null
179        : was === "approved"
180          ? "approve"
181          : was === "rejected"
182            ? "reject"
183            : was === "pending" && canReset
184              ? "reset"
185              : null;
186    if (inverse) inverses.push({ id, version: written.version, intent: inverse, status: written.status });
187    else if (was !== written.status) noUndo++;
188    const note = await recordDone(source, `mention-${intent}`, id, change);
189    return { id, ok: true, message: DECIDED[intent] + (written.purged === false ? PURGE_FAILED : "") + note };
190  });
191
192  const all = [...early, ...outcomes];
193  const extra: Partial<IntentResult> = conflict ? { conflict } : {};
194  let tail = "";
195  if (inverses.length > 0 && inverses.every((i) => i.intent === inverses[0]!.intent)) {
196    extra.undo = {
197      intent: inverses[0]!.intent,
198      fields: { ids: inverses.map((i) => i.id), versions: inverses.map((i) => i.version), statuses: inverses.map((i) => i.status) },
199    };
200  } else if (inverses.length > 0) {
201    tail = " The mentions were in different states before, so there is no single Undo; change them one at a time to reverse it.";
202  }
203  if (intent !== "delete" && noUndo > 0) tail += canReset ? "" : " A decision on a waiting mention has no Undo on this site.";
204  return result(all, summarise(all, DONE_MENTIONS[intent], "mention") + tail, extra);
205}
206
207const DECIDED: Record<MentionIntent, string> = { approve: "Approved.", reject: "Rejected.", reset: "Back to waiting.", delete: "Deleted.", sweep: "" };
208const DONE_MENTIONS: Record<MentionIntent, string> = { approve: "Approved", reject: "Rejected", reset: "Took back the decision on", delete: "Deleted", sweep: "Swept" };