@geekity/cms 0.3.0 → 0.5.0

package/dist/web/conversation.d.ts

@@ -0,0 +1,209 @@
+import type { AdminStore } from '../admin/store.ts';
+import type { Document } from '../content/document.ts';
+import type { ContentStore } from '../content/store.ts';
+import type { FeedComment } from './feeds.ts';
+/**
+ * The conversation under a post, in one shape whatever it is made of, and the
+ * one reader everything that shows a conversation asks.
+ *
+ * The fediverse is only the first thing that can answer a post: native
+ * comments and webmentions land in the same thread, so nothing here is spelled
+ * in ActivityPub's vocabulary. An {@link Interaction} says where it came from
+ * (`source`) and what it is (`kind`), and everything else about it is the same
+ * whether a Mastodon note, a form on this site or somebody else's blog post
+ * produced it.
+ *
+ * Two indexes hold the raw material — `ap_inbox` for what remote servers sent
+ * and `comments` for what the files under `content/_data/comments/` say — and
+ * this module is the only place outside the comment intake that reads either
+ * of them to show somebody a conversation. That is the point of it: the thread
+ * under the post, the post's own comments feed, `/comments/feed/` and the
+ * `source:comments` count on a post feed used to merge the same two indexes in
+ * two implementations, which is two chances to disagree about what a reader
+ * may see. Now there is one {@link ConversationReader}, and the page and the
+ * feed are the same reading.
+ */
+/**
+ * Where an interaction came from.
+ *
+ * `activitypub` is a reply, a like or a boost the site's inbox was sent.
+ * `comment` is the form under the post (TASK-50). `webmention` is another
+ * site's post pointing at this one (TASK-51). All three are the same shape and
+ * thread together, which is the whole point of naming the source rather than
+ * keeping three lists.
+ */
+export type InteractionSource = 'activitypub' | 'comment' | 'webmention';
+/**
+ * What an interaction is.
+ *
+ * `reply` is something somebody wrote; `like` and `boost` are the two ways the
+ * fediverse can point at a post without writing anything. `repost` is a
+ * webmention's word for a boost and is grouped with them, because to a reader
+ * they are the same act under two vocabularies. `mention` is the one thing
+ * none of the others is: somebody's page linking to this one without answering
+ * it (TASK-51).
+ */
+export type InteractionKind = 'reply' | 'like' | 'boost' | 'repost' | 'mention';
+/**
+ * Where an interaction stands with the moderator.
+ *
+ * Everything a remote server sends is `published`: it was published there
+ * before it arrived here, and this site did not decide it. A native comment
+ * carries the status its file gives it, and only an `approved` one is ever put
+ * in a conversation — `pending` and `spam` are named here because that is what
+ * the file can say, not because a template will ever be handed one.
+ */
+export type InteractionStatus = 'published' | 'pending' | 'approved' | 'spam';
+/** Who wrote something, as much as the site knows. */
+export interface InteractionAuthor {
+    /** The best name available: their display name, else their handle, else their id. */
+    readonly name: string;
+    /** `@user@host`, when the source knows or can imply one. */
+    readonly handle: string | null;
+    /** Their profile page, for a reader following the link. */
+    readonly url: string | null;
+    /** Their avatar, when the site knows one. */
+    readonly avatar: string | null;
+    /** Their id, which is what identifies them however they are named. */
+    readonly actorId: string | null;
+}
+/** One thing somebody did to a post: a reply, a like or a boost. */
+export interface Interaction {
+    /** What it is called: the note's id, and what a reply to it names. */
+    readonly id: string;
+    /** Where it came from. */
+    readonly source: InteractionSource;
+    /** Which of the three it is. */
+    readonly kind: InteractionKind;
+    /** Who did it. */
+    readonly author: InteractionAuthor;
+    /** Where it can be read on its own server, or `null` for one with no page. */
+    readonly url: string | null;
+    /** What it says, sanitised and ready to print. Empty for a like or a boost. */
+    readonly content: string;
+    /** When it was published, or when it arrived if it did not say. */
+    readonly published: Date;
+    /** What it answers: the post, or another interaction. `null` for a reaction. */
+    readonly inReplyTo: string | null;
+    /** Whether a reader may see it. */
+    readonly status: InteractionStatus;
+    /** The replies to this one, oldest first. */
+    readonly replies: Interaction[];
+}
+/** How many of each a conversation holds. */
+export interface InteractionCounts {
+    /** Replies, counted through the whole thread rather than the top of it. */
+    readonly replies: number;
+    /** Likes. */
+    readonly likes: number;
+    /** Boosts, reposts included. */
+    readonly boosts: number;
+    /** Mentions: pages that linked to this one without answering it. */
+    readonly mentions: number;
+    /** All four added up: zero is what "no conversation" means. */
+    readonly total: number;
+}
+/** Everything under one post. */
+export interface Conversation {
+    /** The replies to the post itself, oldest first, each carrying its own. */
+    readonly replies: Interaction[];
+    /** The likes, oldest first. */
+    readonly likes: Interaction[];
+    /** The boosts and the reposts, oldest first and in one list. */
+    readonly boosts: Interaction[];
+    /** The pages that linked here without answering, oldest first. */
+    readonly mentions: Interaction[];
+    /** How many of each. */
+    readonly counts: InteractionCounts;
+}
+/** One interaction with the post it is about, which a site-wide list needs. */
+export interface SiteInteraction extends Interaction {
+    /** The post it answers. */
+    readonly post: Document;
+}
+/** What reading a conversation needs: both indexes and the site's origin. */
+export interface ConversationContext {
+    /** Where the fediverse interactions are logged. */
+    readonly admin: AdminStore;
+    /**
+     * Where the posts are, for the site-wide reading: an answer is only worth
+     * showing while the post it is about is there to read.
+     */
+    readonly store: ContentStore;
+    /** The site's public origin, for the post's object id. */
+    readonly baseUrl: string;
+}
+/**
+ * The three questions anything showing a conversation asks.
+ *
+ * Every one of them is answered from both indexes at once, because a reader
+ * does not care which door an answer came in by. The moderation screen and the
+ * notices are not conversation display and keep their own queries: they are
+ * about what a moderator has to decide, which is the one thing a reader never
+ * sees.
+ */
+export interface ConversationReader {
+    /** Everything said about one post, threaded. */
+    readonly thread: (document: Document) => Conversation;
+    /**
+     * How many answers each of these posts has, by permalink: the fediverse
+     * replies and the approved native ones together, which is what a reader
+     * following `source:comments` would actually find on the page.
+     *
+     * Counted off the indexes rather than by reading each thread, because the
+     * number goes into a feed's own validator: a feed whose comment counts moved
+     * is a changed feed, and that has to be cheap for every item of a page.
+     */
+    readonly counts: (documents: readonly Document[]) => Map<string, number>;
+    /**
+     * The site's latest answers, newest first, each with the post it answers.
+     *
+     * One about a post that has since been unpublished or trashed is left out,
+     * because the post it is about is not there to read: the feed would be
+     * showing a conversation about nothing. That filtering happens after the
+     * indexes have paged, so the pages are read until enough survive.
+     */
+    readonly latest: (limit: number) => SiteInteraction[];
+}
+/**
+ * The reader over one site's two indexes.
+ *
+ * The methods are properties rather than prototype methods so that one of them
+ * can be handed out on its own — the renderer is given `conversation.thread`
+ * and nothing else — without anybody having to wrap it in a closure to keep
+ * `this`.
+ */
+export declare function createConversation(context: ConversationContext): ConversationReader;
+/**
+ * The `id` a comment is anchored at on the page.
+ *
+ * Prefixed rather than bare so a comment can never collide with a heading
+ * anchor the post's own Markdown produced.
+ */
+export declare function commentAnchor(id: string): string;
+/**
+ * Everything said in a conversation, at every depth and in no order: the
+ * replies and the mentions.
+ *
+ * The likes and the boosts are left out because they say nothing. A feed item
+ * is somebody's words, and "@ada liked this" has none to carry — a reader
+ * polling a comments feed would get an entry with an empty body and no way to
+ * tell what it was for.
+ */
+export declare function spokenIn(conversation: Conversation): Interaction[];
+/**
+ * Interactions as a comments feed carries them: newest first, at most `limit`,
+ * and every link absolute.
+ *
+ * The one place an interaction becomes a feed item, so the post's feed and the
+ * site's cannot disagree about what a comment's `guid` or `link` is. The HTML
+ * is handed over as it stands and sanitised by the feed itself, at the last
+ * moment before it becomes bytes this site publishes.
+ */
+export declare function feedComments(said: readonly (Interaction & {
+    post?: Document | undefined;
+})[], options: {
+    baseUrl: string;
+    limit: number;
+}): FeedComment[];
+//# sourceMappingURL=conversation.d.ts.map

package/dist/web/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/web/conversation.ts"],"names":[],"mappings":"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"}