app/lib/mentions.server.ts

Functions

Imports

It imports app/db/schema.ts, app/lib/people.server.ts, app/lib/projects.server.ts, app/lib/roles.ts, app/lib/sites.server.ts. Imported by app/routes/mentions.api.ts, app/routes/mentions.tsx.

Source

1// Webmentions on a site project (site-api v0.5.0, the mentions group): the queue of what other sites
2// sent, and the Owner's decisions on it. Mentions are text strangers chose, so they are shown as text
3// and decided here, one site write each, in order. One failing never stops the rest, and every outcome
4// is said in plain words.
5//
6// Roles, checked here so the page, the JSON endpoint and any later tool meet the same rule:
7// the inbox belongs to Dustin alone (his design decision, 2026-09-26), so reading the queue (read_mentions) and
8// deciding (decide_mention) are both the Owner's. Change roles.ts, not this file, to open it wider.
9//
10// Authorship: every write the site carried out writes one row in mention_decisions (migration 0011),
11// with the change id Carrel sent the site so the two histories join. A refused write writes nothing.
12// The write and the site's cache purge are one unit on the site's side; Carrel reports its answer.
13
14import { MentionId, Version, type MentionList, type MentionStatus } from "@dustinedwards/site-api";
15import { MENTION_FILTERS, type MentionFilter } from "@dustinedwards/site-api/admin";
16import { SiteApiError } from "@dustinedwards/site-api/client";
17import { drizzle } from "drizzle-orm/d1";
18
19import { mentionDecisions } from "~/db/schema";
20import type { Viewer } from "~/lib/people.server";
21import type { SiteProject } from "~/lib/projects.server";
22import { can, type Action } from "~/lib/roles";
23import { siteClient, SiteNotConnected } from "~/lib/sites.server";
24
25export const MAX_MENTION_BATCH = 100;
26const MENTIONS_PER_PAGE = 50;
27
28export type { MentionFilter };
29
30export function isMentionFilter(value: string | null | undefined): value is MentionFilter {
31  return (MENTION_FILTERS as readonly string[]).includes(value ?? "");
32}
33
34export type MentionOp = "approve" | "reject" | "delete";
35
36/** One mention to act on: its id, the version the person saw, and the status they saw it in. */
37export type MentionTarget = { id: string; version: string; status: MentionStatus };
38
39/** One mention's outcome. `ok` false means this mention was left as it was; the message says why. */
40export type MentionResult = { id: string; ok: boolean; message: string };
41
42export type SweepResult = { ok: true; message: string; removed: { failed: number; rejected: number }; recorded: boolean } | { ok: false; message: string };
43
44/** Who did it: the person, and the AI client when it came through the AI door (credited in the record). */
45export type MentionActor = { viewer: Viewer; client?: string };
46
47function requireCan(project: { role: SiteProject["role"] }, action: Action) {
48  if (!can(project.role, action)) throw new Response("Forbidden", { status: 403 });
49}
50
51/**
52 * Whether the site moderates mentions through Carrel, from its meta. A site on an older site API, or
53 * one whose adapter has no mentions, says no and the reason is plain; a site that does not answer says that.
54 */
55export async function mentionsOffered(
56  env: Env,
57  project: SiteProject,
58  fetcher?: typeof fetch,
59): Promise<{ offered: true } | { offered: false; reason: string }> {
60  requireCan(project, "read_mentions");
61  try {
62    const meta = await siteClient(env, project.site, fetcher).meta();
63    return meta.capabilities.mentions === true ? { offered: true } : { offered: false, reason: "This site does not receive webmentions through Carrel yet." };
64  } catch (error) {
65    if (error instanceof SiteNotConnected) return { offered: false, reason: error.detail };
66    console.error(JSON.stringify({ meta: "failed", error: String(error) }));
67    return { offered: false, reason: "The site did not answer, so Carrel cannot tell whether it receives webmentions." };
68  }
69}
70
71/**
72 * One page of the queue. With no filter the queue opens on Pending, and on All when nothing is
73 * pending, as the site's own page does. The counts and the number a sweep would remove cover the whole queue.
74 */
75export async function listMentions(
76  env: Env,
77  project: SiteProject,
78  query: { filter?: MentionFilter | null; cursor?: string },
79  fetcher?: typeof fetch,
80): Promise<{ filter: MentionFilter; list: MentionList }> {
81  requireCan(project, "read_mentions");
82  const client = siteClient(env, project.site, fetcher);
83  const page = (filter: MentionFilter) =>
84    client.mentions.list({
85      limit: MENTIONS_PER_PAGE,
86      ...(filter === "all" ? {} : { status: filter }),
87      ...(query.cursor ? { cursor: query.cursor } : {}),
88    });
89  if (query.filter) return { filter: query.filter, list: await page(query.filter) };
90  const pending = await page("pending");
91  if (pending.items.length > 0 || pending.counts.pending > 0) return { filter: "pending", list: pending };
92  return { filter: "all", list: await page("all") };
93}
94
95const MESSAGES: Record<MentionOp, { done: string }> = {
96  approve: { done: "Approved." },
97  reject: { done: "Rejected." },
98  delete: { done: "Deleted." },
99};
100
101const STALE = "This mention changed on the site since the page loaded. It was left as it was; reload to see it.";
102
103/** What went wrong for one mention, said plainly. Anything unexpected is logged and reported, never dropped. */
104function failure(id: string, error: unknown): MentionResult {
105  if (error instanceof SiteNotConnected) return { id, ok: false, message: error.detail };
106  if (error instanceof SiteApiError) {
107    if (error.status === 501) return { id, ok: false, message: "The site does not moderate mentions through Carrel yet." };
108    if (error.body?.error === "version-conflict") return { id, ok: false, message: STALE };
109    if (error.status === 404) return { id, ok: false, message: "The site no longer has this mention. It may have been deleted or swept." };
110    if (error.body?.error === "refused") return { id, ok: false, message: error.body.message };
111    console.error(JSON.stringify({ mentions: "item-failed", id, status: error.status, code: error.body?.error ?? null }));
112    return { id, ok: false, message: "The site did not accept this change. The mention was left as it was." };
113  }
114  console.error(JSON.stringify({ mentions: "item-failed", id, error: String(error) }));
115  return { id, ok: false, message: "Something went wrong with this mention. It was left as it was." };
116}
117
118/** Said when the write moved but the site could not clear its cache: the post's page keeps the old mentions for a while. */
119const PURGE_FAILED = " The site could not clear its cache, so the post's page may show the old mentions until its cache expires.";
120
121/** The ids and versions to act on: unique, each shaped as a site could hold it. Anything else is reported, not sent. */
122export function parseTargets(raw: unknown): { targets: MentionTarget[]; invalid: string[] } {
123  const targets: MentionTarget[] = [];
124  const invalid: string[] = [];
125  const seen = new Set<string>();
126  if (!Array.isArray(raw)) return { targets, invalid };
127  for (const entry of raw) {
128    const e = (entry ?? {}) as Record<string, unknown>;
129    const id = typeof e.id === "string" ? e.id : "";
130    const status = ["unverified", "pending", "approved", "rejected", "failed"].find((s) => s === e.status) as MentionStatus | undefined;
131    if (seen.has(id)) continue;
132    seen.add(id);
133    if (!MentionId.safeParse(id).success || !Version.safeParse(e.version).success || !status) invalid.push(id || "(no id)");
134    else targets.push({ id, version: e.version as string, status });
135  }
136  return { targets, invalid };
137}
138
139async function record(
140  env: Env,
141  project: SiteProject,
142  actor: MentionActor,
143  row: { mentionId: string | null; action: "approve" | "reject" | "delete" | "sweep"; statusBefore: MentionStatus | null; statusAfter: MentionStatus | null; changeId: string },
144): Promise<boolean> {
145  try {
146    await drizzle(env.DB).insert(mentionDecisions).values({
147      projectId: project.id,
148      personId: actor.viewer.id,
149      client: actor.client ?? null,
150      ...row,
151    });
152    return true;
153  } catch (error) {
154    console.error(JSON.stringify({ record: "failed", action: row.action, mentionId: row.mentionId, changeId: row.changeId, error: String(error) }));
155    return false;
156  }
157}
158
159/**
160 * Approves, rejects or deletes each mention, in order, each with its own change id and its own
161 * authorship row. The role is checked once before the site is asked anything. Each write carries the
162 * version the person saw, so a mention the site changed since (re-sent, decided elsewhere) is refused
163 * as stale and stays.
164 */
165export async function decideMentions(
166  env: Env,
167  project: SiteProject,
168  actor: MentionActor,
169  op: MentionOp,
170  rawTargets: unknown,
171  fetcher?: typeof fetch,
172): Promise<MentionResult[]> {
173  requireCan(project, "decide_mention");
174  const { targets, invalid } = parseTargets(rawTargets);
175  if (targets.length + invalid.length === 0) throw new Response("Choose at least one mention.", { status: 400 });
176  if (targets.length + invalid.length > MAX_MENTION_BATCH) throw new Response(`At most ${MAX_MENTION_BATCH} mentions at a time.`, { status: 400 });
177
178  const results: MentionResult[] = invalid.map((id) => ({ id, ok: false, message: "That is not a mention Carrel can send to the site, so it was not sent." }));
179  const client = siteClient(env, project.site, fetcher);
180  for (const target of targets) {
181    const changeId = crypto.randomUUID();
182    try {
183      let statusAfter: MentionStatus | null = null;
184      let purged: boolean | null;
185      if (op === "delete") {
186        ({ purged } = await client.mentions.delete(target.id, { expectedVersion: target.version, changeId }));
187      } else {
188        const written = await client.mentions.decide(target.id, { decision: op, expectedVersion: target.version, changeId });
189        statusAfter = written.status;
190        purged = written.purged;
191      }
192      const recorded = await record(env, project, actor, { mentionId: target.id, action: op, statusBefore: target.status, statusAfter, changeId });
193      results.push({
194        id: target.id,
195        ok: true,
196        message: MESSAGES[op].done + (purged === false ? PURGE_FAILED : "") + (recorded ? "" : " Carrel could not save the record of it; tell the Owner."),
197      });
198    } catch (error) {
199      results.push(failure(target.id, error));
200    }
201  }
202  return results;
203}
204
205/** Removes the failed and rejected mentions past the site's retention windows. Owner only; the site decides what is expired. */
206export async function sweepMentions(env: Env, project: SiteProject, actor: MentionActor, fetcher?: typeof fetch): Promise<SweepResult> {
207  requireCan(project, "decide_mention");
208  const changeId = crypto.randomUUID();
209  try {
210    const { removed } = await siteClient(env, project.site, fetcher).mentions.sweep(changeId);
211    const recorded = await record(env, project, actor, { mentionId: null, action: "sweep", statusBefore: null, statusAfter: null, changeId });
212    return {
213      ok: true,
214      removed,
215      recorded,
216      message:
217        `Removed ${removed.failed} failed and ${removed.rejected} rejected mention${removed.failed + removed.rejected === 1 ? "" : "s"} past their retention window.` +
218        (recorded ? "" : " Carrel could not save the record of it; tell the Owner."),
219    };
220  } catch (error) {
221    const { message } = failure("sweep", error);
222    return { ok: false, message };
223  }
224}
225
226export type { MentionList };