src/contract/mentions.ts

Functions

None: it only declares types or values.

Imports

It imports src/contract/base.ts. Imported by src/contract.ts.

Source

1// The mentions group (v0.5.0).
2
3import { z } from "zod";
4import { ChangeId, ContentId, Timestamp, Version } from "./base.js";
5
6/** A site's id for one received mention, as text: a row id such as 41. Never a path. */
7export const MentionId = ContentId;
8
9/**
10 * Where a mention is in the site's moderation queue. unverified: received, the sender's page not yet
11 * fetched. pending: the link is really there, awaiting a decision. approved: shown on the post.
12 * rejected: kept, so a re-sender does not reappear as new. failed: verification found no link.
13 */
14export const MentionStatus = z.enum(["unverified", "pending", "approved", "rejected", "failed"]);
15
16export const MentionItem = z.object({
17  id: MentionId,
18  status: MentionStatus,
19  /** The page the sender says links to us. Text from a stranger: never a link. */
20  sourceUrl: z.string().min(1).max(2000),
21  /** The content id the mention targets, such as a post slug. */
22  targetId: z.string().min(1).max(300),
23  authorName: z.string().max(500).nullable(),
24  authorUrl: z.string().max(2000).nullable(),
25  excerpt: z.string().max(5000).nullable(),
26  /** Why verification failed, in the site's fixed words; null unless failed. */
27  failureReason: z.string().max(500).nullable(),
28  receivedAt: Timestamp,
29  verifiedAt: Timestamp.nullable(),
30  decidedAt: Timestamp.nullable(),
31  /** Opaque, like a content version: it must move whenever the status, the verification or the decision does. */
32  version: Version,
33});
34
35export const MentionListQuery = z.object({
36  status: MentionStatus.optional(),
37  /** v0.6.0: words in the source address, the author or the excerpt. */
38  q: z.string().max(200).optional(),
39  /** v0.6.0: only the mentions of this content id, such as a post slug. */
40  targetId: z.string().min(1).max(300).optional(),
41  cursor: z.string().max(500).optional(),
42  limit: z.coerce.number().int().min(1).max(200).default(50),
43});
44
45/** How many mentions the site holds in each status. */
46export const MentionCounts = z.object({
47  unverified: z.number().int().min(0),
48  pending: z.number().int().min(0),
49  approved: z.number().int().min(0),
50  rejected: z.number().int().min(0),
51  failed: z.number().int().min(0),
52});
53
54export const MentionList = z.object({
55  items: z.array(MentionItem),
56  nextCursor: z.string().nullable(),
57  /** Across the whole queue, not the page, so a filter can show its count. */
58  counts: MentionCounts,
59  /** What a sweep would remove now, by status (the site's retention windows). */
60  expiring: z.object({ failed: z.number().int().min(0), rejected: z.number().int().min(0) }),
61  /** The filters of v0.6.0 the site applied, echoed. Absent: the site did not filter by q or targetId. */
62  filtered: z.object({ q: z.string().max(200).optional(), targetId: z.string().max(300).optional() }).optional(),
63});
64
65/** `reset` (v0.6.0, optional per site) takes an approved or rejected mention back to pending, so a decision can be undone. */
66export const MENTION_DECISIONS = ["approve", "reject", "reset"] as const;
67
68export const MentionDecideInput = z.object({
69  decision: z.enum(MENTION_DECISIONS),
70  expectedVersion: Version,
71  changeId: ChangeId,
72});
73
74export const MentionWriteResult = z.object({
75  id: MentionId,
76  status: MentionStatus,
77  /** The mention's version after the write. */
78  version: Version,
79  changeId: ChangeId,
80  /** Whether the site purged the target's cached page: false when the purge failed, null when there was none to run. */
81  purged: z.boolean().nullable(),
82});
83
84export const MentionDeleteQuery = z.object({
85  expectedVersion: Version,
86  changeId: ChangeId,
87});
88
89export const MentionDeleteResult = z.object({
90  id: MentionId,
91  deleted: z.literal(true),
92  changeId: ChangeId,
93  purged: z.boolean().nullable(),
94});
95
96/** Sweeping removes the mentions past the site's retention windows: failed and rejected ones. It names no version, since it is not about one mention. */
97export const MentionSweepInput = z.object({
98  changeId: ChangeId,
99});
100
101export const MentionSweepResult = z.object({
102  changeId: ChangeId,
103  removed: z.object({ failed: z.number().int().min(0), rejected: z.number().int().min(0) }),
104});
105
106export type MentionStatus = z.infer<typeof MentionStatus>;
107export type MentionItem = z.infer<typeof MentionItem>;
108export type MentionListQuery = z.infer<typeof MentionListQuery>;
109export type MentionCounts = z.infer<typeof MentionCounts>;
110export type MentionList = z.infer<typeof MentionList>;
111export type MentionDecideInput = z.infer<typeof MentionDecideInput>;
112export type MentionWriteResult = z.infer<typeof MentionWriteResult>;
113export type MentionDeleteQuery = z.infer<typeof MentionDeleteQuery>;
114export type MentionDeleteResult = z.infer<typeof MentionDeleteResult>;
115export type MentionSweepInput = z.infer<typeof MentionSweepInput>;
116export type MentionSweepResult = z.infer<typeof MentionSweepResult>;