@geekity/cms 0.30.0 → 0.32.0

package/dist/comments/akismet.js

@@ -1,6 +1,5 @@
-import { rm } from 'node:fs/promises';
-import path from 'node:path';
-import { readFileIfPresentSync, writeFileAtomically } from '../files/atomic.js';
+import { AKISMET } from '../settings/akismet.js';
+import { messageOf } from '../util/errors.js';
 import { COMMENT_FIELDS } from './submission.js';
 /**
  * Akismet, as the one {@link CommentChecker} this package ships.
@@ -11,18 +10,16 @@ import { COMMENT_FIELDS } from './submission.js';
  *
  * Two things make it optional at runtime rather than at build time:
  *
- * - **The key is a credential**, so it lives in `data/akismet.json` at mode
- *   `0600` beside the password hashes and the actor's private keys, and never
- *   in `content/_data/site.json`, which is public, in git and published with
- *   the site.
- * - **The key file is read on every call**, so a key pasted into the settings
+ * - **The key is a credential**, so it is the secret `akismet.key` setting,
+ *   kept in `data/akismet.json` at mode `0600` or set by
+ *   `GEEKITY_AKISMET__KEY`, and never in `content/_data/site.json`, which is
+ *   public, in git and published with the site.
+ * - **The key is read on every call**, so a key pasted into the settings
  *   screen starts filtering the next comment and a key removed stops filtering
  *   at once. Without one, nothing is sent anywhere and the verdict is
  *   `unknown` — the site's own rules decide, exactly as they did before
  *   anybody had heard of Akismet.
  */
-/** Where the key lives, under `dataDir`. */
-export const AKISMET_KEY_FILE = 'akismet.json';
 /** The API this speaks. */
 export const AKISMET_ENDPOINT = 'https://rest.akismet.com/1.1';
 /**
@@ -40,59 +37,23 @@ export const AKISMET_USER_AGENT = 'Geekity CMS/1.0 | Akismet/1.1';
  */
 export const AKISMET_TIMEOUT_MS = 10_000;
 /**
- * The stored key, or `undefined` when the site has none.
- *
- * Read tolerantly and synchronously, like every other file this CMS treats as
- * truth: a file that will not parse, or one with no key in it, is a site with
- * no Akismet rather than a site that will not boot.
- */
-export function readAkismetKey(dataDir) {
-    const raw = readFileIfPresentSync(akismetKeyPath(dataDir));
-    if (raw === undefined)
-        return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof parsed !== 'object' || parsed === null)
-        return undefined;
-    const file = parsed;
-    const key = typeof file['key'] === 'string' ? file['key'].trim() : '';
-    if (key === '')
-        return undefined;
-    const status = file['status'];
-    return {
-        key,
-        status: status === 'valid' || status === 'invalid' ? status : 'unchecked',
-        checkedAt: typeof file['checkedAt'] === 'string' ? file['checkedAt'] : '',
-    };
-}
-/** Write the key, private to the account the site runs as. */
-export async function writeAkismetKey(dataDir, record) {
-    await writeFileAtomically(akismetKeyPath(dataDir), `${JSON.stringify(record, null, 2)}\n`, {
-        mode: 0o600,
-    });
-}
-/** Forget the key, which is how a site turns Akismet off. */
-export async function removeAkismetKey(dataDir) {
-    await rm(akismetKeyPath(dataDir), { force: true });
-}
-/** Where one site's key file is. */
-export function akismetKeyPath(dataDir) {
-    return path.join(dataDir, AKISMET_KEY_FILE);
-}
-/**
- * Ask Akismet whether a key is one of theirs.
- *
  * Three answers rather than two, because "we could not ask" is not "no": a key
  * typed while the machine is offline should not be reported as a bad key, and
  * the settings screen says which of the two happened.
  */
 export async function verifyAkismetKey(options) {
-    const body = new URLSearchParams({ api_key: options.key, blog: options.blog });
+    const key = await options.settings.get(AKISMET.key);
+    if (key === '')
+        return undefined;
+    const status = await askAboutKey(key, options);
+    await options.settings.set('akismet', new Map([
+        ['status', status],
+        ['checked_at', options.at.toISOString()],
+    ]), options.by);
+    return status;
+}
+async function askAboutKey(key, options) {
+    const body = new URLSearchParams({ api_key: key, blog: options.blog });
     let answer;
     try {
         answer = await post(`${AKISMET_ENDPOINT}/verify-key`, body, options.fetch, options.timeoutMs);
@@ -123,11 +84,12 @@ export function createAkismetChecker(options) {
     };
     /** Send one call, or nothing at all when the site has no key. */
     async function send(method, fields) {
-        const stored = readAkismetKey(options.dataDir);
-        if (stored === undefined)
+        const key = await options.settings.get(AKISMET.key);
+        if (key === '')
             return undefined;
+        const language = await options.language();
         try {
-            const answer = await post(`${AKISMET_ENDPOINT}/${method}`, fields(stored.key), options.fetch, options.timeoutMs);
+            const answer = await post(`${AKISMET_ENDPOINT}/${method}`, fields(key, language), options.fetch, options.timeoutMs);
             if (!answer.ok) {
                 warn(`Akismet answered ${method} with ${String(answer.status)}.${help(answer)}`);
                 return undefined;
@@ -141,7 +103,7 @@ export function createAkismetChecker(options) {
     }
     return {
         async check(submission) {
-            const answer = await send('comment-check', (key) => checkFields(key, submission, options));
+            const answer = await send('comment-check', (key, language) => checkFields(key, language, submission, options));
             if (answer === undefined)
                 return 'unknown';
             const said = answer.body.trim();
@@ -160,15 +122,15 @@ export function createAkismetChecker(options) {
             return 'unknown';
         },
         async reportSpam(report) {
-            await send('submit-spam', (key) => reportFields(key, report, options));
+            await send('submit-spam', (key, language) => reportFields(key, language, report, options));
         },
         async reportHam(report) {
-            await send('submit-ham', (key) => reportFields(key, report, options));
+            await send('submit-ham', (key, language) => reportFields(key, language, report, options));
         },
     };
 }
 /** The fields one `comment-check` carries. */
-function checkFields(key, submission, options) {
+function checkFields(key, language, submission, options) {
     const { comment } = submission;
     // A webmention is a page linking here rather than a form somebody filled in,
     // so it has no honeypot to name; a contact message is a form like a
@@ -178,7 +140,7 @@ function checkFields(key, submission, options) {
         api_key: key,
         blog: submission.baseUrl,
         blog_charset: 'UTF-8',
-        blog_lang: blogLang(options.language()),
+        blog_lang: blogLang(language),
         user_ip: submission.address,
         user_agent: submission.userAgent,
         referrer: submission.referrer,
@@ -209,13 +171,13 @@ function checkFields(key, submission, options) {
  * The content, the author and the permalink are what is left, and they are
  * what a correction is mostly about.
  */
-function reportFields(key, report, options) {
+function reportFields(key, language, report, options) {
     const { comment } = report;
     return fields({
         api_key: key,
         blog: report.baseUrl,
         blog_charset: 'UTF-8',
-        blog_lang: blogLang(options.language()),
+        blog_lang: blogLang(language),
         permalink: report.url,
         comment_type: comment.source === 'webmention' ? 'webmention' : 'comment',
         comment_author: comment.author.name,
@@ -248,9 +210,6 @@ function blogLang(language) {
 function help(answer) {
     return answer.debugHelp === undefined ? '' : ` ${answer.debugHelp}`;
 }
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /** POST a urlencoded body to Akismet and read the answer. */
 async function post(url, body, client, timeoutMs) {
     const call = client ?? globalThis.fetch;

package/dist/comments/akismet.js.map

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

package/dist/comments/conversation.d.ts

@@ -0,0 +1,340 @@
+import type { Document } from '../content/document.ts';
+import type { RsvpValue } from '../content/rsvp.ts';
+import type { SiteSettings } from '../site/settings.ts';
+import type { AdminStore, PostComment } from '../store/admin-store.ts';
+/**
+ * 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). `post` is a reply post a user of
+ * this site wrote, whose `in-reply-to` names the post or something said under
+ * it (TASK-300). All four are the same shape and thread together, which is the
+ * whole point of naming the source rather than keeping four lists.
+ */
+export type InteractionSource = 'activitypub' | 'comment' | 'webmention' | 'post';
+/**
+ * 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: always a same-origin path, never
+     * the remote URL, so a reader's browser asks this site for it (TASK-134).
+     */
+    readonly avatar: string | null;
+    /** Their id, which is what identifies them however they are named. */
+    readonly actorId: string | null;
+    /**
+     * Where to follow what they publish, when the site knows (TASK-324): a
+     * webmention author's h-card or site, or a site user's author feed. A
+     * visitor's own website is only what they typed, and a fediverse actor
+     * publishes no feed the site knows of, so both are `null`.
+     */
+    readonly feed: string | null;
+    /**
+     * The site user they are, by username, else `null`: whoever a reply post
+     * is by, or whoever a stored comment names (TASK-337). A theme vouches for
+     * the link of a site user and of nobody else.
+     */
+    readonly username: 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;
+    /**
+     * Its key (decision-51): a stored comment's id, else the key of its guid.
+     * The one thing in its anchor, `#comment-{key}`, and its replies feed,
+     * `/replies/{key}/`.
+     */
+    readonly key: string;
+    /**
+     * What the comments feeds call it, and what a reply to it names in
+     * `source:inReplyTo`: a stored form comment's page, a stored comment's
+     * origin or else its url, and anything else's id.
+     */
+    readonly guid: string;
+    /**
+     * Whether it was imported from another system (TASK-336): shown in the
+     * thread like any other, and carried by no feed and no reply count.
+     */
+    readonly migrated: boolean;
+    /** 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: ThreadReply[];
+    /**
+     * What a reply that is an RSVP says (TASK-198): its `rsvp` value and the
+     * words for it. A webmention carries one, and so does a fediverse answer
+     * to an event (TASK-200).
+     */
+    readonly rsvp?: {
+        readonly value: RsvpValue;
+        readonly label: string;
+    };
+}
+/**
+ * A comment a reader may not see, standing in the thread for the replies to it
+ * that a reader may (TASK-325): it is waiting for a moderator, filed as spam or
+ * deleted. It names nobody and says nothing, and there is one only while a
+ * visible reply sits under it.
+ */
+export interface WithheldReply {
+    /** The hidden comment's id. */
+    readonly id: string;
+    /** Its key, so its anchor on the post is still there. */
+    readonly key: string;
+    readonly withheld: true;
+    /** The replies under it, oldest first, at least one of them visible. */
+    readonly replies: ThreadReply[];
+}
+/** One entry of a thread: a reply, or the placeholder for a hidden one. */
+export type ThreadReply = Interaction | WithheldReply;
+/** 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;
+    /** RSVPs to an event, one per person, in every group. */
+    readonly rsvps: number;
+    /** All of them 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: ThreadReply[];
+    /** 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[];
+    /**
+     * The answers to an event (TASK-200), grouped as going, maybe, interested
+     * and not going, each group oldest first and only when it has somebody in
+     * it. Empty on a post that is no event.
+     */
+    readonly rsvps: RsvpGroup[];
+    /** How many of each. */
+    readonly counts: InteractionCounts;
+}
+/** Everybody who gave an event one answer. */
+export interface RsvpGroup {
+    readonly value: RsvpValue;
+    readonly label: string;
+    /** Each person's latest answer, oldest first, each an RSVP interaction. */
+    readonly people: Interaction[];
+}
+/**
+ * Something said in a conversation, with the reply it sits under (TASK-324):
+ * what the comments feeds name as what it answers.
+ */
+export interface Placed extends Interaction {
+    /**
+     * The visible reply it answers, or `null` for the post. A hidden comment in
+     * between is passed over, the way the thread already passes over a
+     * withdrawn note, so a reader walking the feeds reaches every visible reply.
+     */
+    readonly parent: Interaction | null;
+}
+/** One interaction with the post it is about, which a site-wide list needs. */
+export interface SiteInteraction extends Placed {
+    /** The post it answers. */
+    readonly post: Document;
+    /**
+     * Who wrote the reply it answers, when it answers one a reader can see
+     * (TASK-318), and `null` for an answer to the post itself.
+     */
+    readonly replyingTo: string | null;
+}
+/**
+ * The site settings a conversation is read with: who the site's own posts are
+ * by when they name nobody, and whether comments are on.
+ */
+export type ConversationSite = Pick<SiteSettings, 'author' | 'title' | 'comments' | 'comments_close_after_days'>;
+/**
+ * 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, site: ConversationSite) => Conversation;
+    /**
+     * How many visible replies answer each of these documents directly, by
+     * permalink: what a reader following `source:comments` finds in its
+     * `/replies/` feed (TASK-324). Read off each thread, since that is the only
+     * reading that knows which replies a reader sees and where they sit.
+     */
+    readonly counts: (documents: readonly Document[], site: ConversationSite) => 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, site: ConversationSite) => SiteInteraction[];
+    /**
+     * One native comment as its own page reads it (TASK-318), or `undefined`
+     * for an id that names no approved comment written on this site. The post
+     * comes back in whatever state it is in, so the page can answer as the post
+     * itself would.
+     */
+    readonly comment: (id: string, site: ConversationSite) => CommentThread | undefined;
+    /**
+     * The reply on a post that a URL names, or `undefined` (TASK-319):
+     * a comment by its own page or by the post's `#comment-` anchor, a
+     * webmention by the page it was sent from, a fediverse reply by its url or
+     * its id. Every stored comment counts whatever its status, because what a
+     * reply answers is a fact about it, and whether a reader may see the one it
+     * answers is decided when the thread is read.
+     */
+    readonly replyNamed: (document: Document, url: string, site: ConversationSite) => Interaction | undefined;
+    /**
+     * What a URL names on this site, while a reader may see it: a reply (a
+     * comment by its page or its anchor, a webmention by the page it was sent
+     * from, a fediverse reply by its id or url, a reply post by its permalink)
+     * with the post it is on, or a served post or page itself (TASK-300,
+     * TASK-326). What a reply post answering it cites, instead of fetching a page.
+     */
+    readonly heldAt: (url: string, site: ConversationSite) => HeldAt | undefined;
+    /**
+     * What a key names and its direct replies (TASK-324, decision-51), or
+     * `undefined`: a served post or page, or a reply a reader can see.
+     */
+    readonly repliesTo: (key: string, site: ConversationSite) => RepliesOf | undefined;
+    /**
+     * The document whose conversation a URL is in (TASK-320): the post a
+     * comment's page or anchor is on, the post a webmention was sent to, the
+     * post a fediverse reply answers however deep, or the document at the URL.
+     */
+    readonly documentOf: (url: string) => Document | undefined;
+    /**
+     * Every page in the conversation a document is in that answers something
+     * off this site, with what a reader sees under it (TASK-320): what a
+     * salmention is sent from. A reply post answers its `in-reply-to`; a
+     * comment's own page answers the webmention reply it is under. One
+     * answering something here has nobody to tell: this site already knows.
+     */
+    readonly upstreams: (document: Document, site: ConversationSite) => Upstream[];
+}
+/** One page of this site's answering a page elsewhere (TASK-320). */
+export interface Upstream {
+    /** The document the page is, or that the comment is on. */
+    readonly post: Document;
+    /** The page, absolute: a reply post's permalink or a comment's own page. */
+    readonly source: string;
+    /** What it answers, off this site. */
+    readonly target: string;
+    /** The replies a reader sees under it, as its page prints them. */
+    readonly replies: readonly ThreadReply[];
+}
+/** What one `/replies/` feed is about, and what is in it (TASK-324). */
+export interface RepliesOf {
+    /** The document whose conversation it is. */
+    readonly post: Document;
+    /** The reply whose replies these are, or `null` for the document's own. */
+    readonly reply: Interaction | null;
+    /** The visible replies directly under it, each carrying its own. */
+    readonly replies: Placed[];
+}
+/** What {@link ConversationReader.heldAt} found: a reply and the post it is on, or a post. */
+export type HeldAt = {
+    readonly kind: 'reply';
+    readonly post: Document;
+    readonly reply: Interaction;
+} | {
+    readonly kind: 'document';
+    readonly post: Document;
+    readonly author: InteractionAuthor;
+};
+/** A native comment, what it answers and what answers it (TASK-318). */
+export interface CommentThread {
+    /** The post it is on. */
+    readonly post: Document;
+    /** The comment, carrying its replies at every depth as the thread does. */
+    readonly comment: Interaction;
+    /**
+     * What it answers, from the top-level comment down to its parent. `null`
+     * is an ancestor a reader may not see: one waiting for a moderator, filed
+     * as spam, deleted or withdrawn.
+     */
+    readonly ancestors: readonly (Interaction | null)[];
+}
+/**
+ * The URLs a reply post can answer a native comment by: its own page, and its
+ * anchor on the post at this absolute permalink.
+ */
+export declare function commentNames(id: string, permalink: string, baseUrl: string): string[];
+/**
+ * The stored comment holding a fediverse note or activity id as its origin:
+ * one imported from the site this one replaced, keyed by that id as it would
+ * have been had it arrived here (TASK-336). A delivery or a fetch of the same
+ * id is that comment again, and the stored one wins, since it is the one the
+ * moderator decided on and the thread anchors.
+ */
+export declare function heldComment(admin: AdminStore, id: string): PostComment | undefined;
+/**
+ * The `id` a thread entry is anchored at on the page, by its key.
+ *
+ * Prefixed rather than bare so a comment can never collide with a heading
+ * anchor the post's own Markdown produced.
+ */
+export declare function commentAnchor(key: string): string;
+/** The key of the comment whose page a path is, or `undefined` (TASK-319). */
+export declare function commentKeyAt(pathname: string): string | undefined;
+/** The entry of a thread with this key that a reader can see, at any depth. */
+export declare function visibleReply(replies: readonly ThreadReply[], key: string): Interaction | undefined;
+export declare function isWithheld(reply: ThreadReply): reply is WithheldReply;
+//# sourceMappingURL=conversation.d.ts.map

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

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

package/dist/comments/conversation.js

@@ -0,0 +1,51 @@
+import { COMMENT_PAGE_PREFIX, commentPageHref, isKey, repliesKey } from '../content/guids.js';
+import { absoluteUrl } from '../util/url.js';
+/**
+ * The URLs a reply post can answer a native comment by: its own page, and its
+ * anchor on the post at this absolute permalink.
+ */
+export function commentNames(id, permalink, baseUrl) {
+    return [absoluteUrl(commentPageHref(id), baseUrl), `${permalink}#${commentAnchor(id)}`];
+}
+/**
+ * The stored comment holding a fediverse note or activity id as its origin:
+ * one imported from the site this one replaced, keyed by that id as it would
+ * have been had it arrived here (TASK-336). A delivery or a fetch of the same
+ * id is that comment again, and the stored one wins, since it is the one the
+ * moderator decided on and the thread anchors.
+ */
+export function heldComment(admin, id) {
+    const comment = admin.getComment(repliesKey(id));
+    return comment?.origin === id ? comment : undefined;
+}
+/**
+ * The `id` a thread entry is anchored at on the page, by its key.
+ *
+ * Prefixed rather than bare so a comment can never collide with a heading
+ * anchor the post's own Markdown produced.
+ */
+export function commentAnchor(key) {
+    return `comment-${key}`;
+}
+/** The key of the comment whose page a path is, or `undefined` (TASK-319). */
+export function commentKeyAt(pathname) {
+    if (!pathname.startsWith(COMMENT_PAGE_PREFIX) || !pathname.endsWith('/'))
+        return undefined;
+    const key = pathname.slice(COMMENT_PAGE_PREFIX.length, -1);
+    return isKey(key) ? key : undefined;
+}
+/** The entry of a thread with this key that a reader can see, at any depth. */
+export function visibleReply(replies, key) {
+    for (const reply of replies) {
+        if (!isWithheld(reply) && reply.key === key)
+            return reply;
+        const found = visibleReply(reply.replies, key);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+export function isWithheld(reply) {
+    return 'withheld' in reply;
+}
+//# sourceMappingURL=conversation.js.map

package/dist/comments/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/comments/conversation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAI9F,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAwU7C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,SAAiB,EAAE,OAAe;IACzE,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,SAAS,IAAI,aAAa,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB,EAAE,EAAU;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,OAAO,OAAO,EAAE,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,WAAW,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3F,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAC1B,OAA+B,EAC/B,GAAW;IAEX,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QAC1D,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,OAAO,UAAU,IAAI,KAAK,CAAC;AAC7B,CAAC"}

package/dist/comments/form.d.ts

@@ -110,14 +110,14 @@ export declare const COMMENT_REPLY_PARAM = "reply_to";
  */
 export declare const COMMENT_NOTICES: Readonly<Record<string, string>>;
 /** A fresh, empty form for a post that is taking comments. */
-export declare function commentForm(document: Document, now?: Date, notifiable?: boolean): CommentFormContext;
+export declare function commentForm(document: Document, now: Date, notifiable?: boolean): CommentFormContext;
 /**
  * The same form with what somebody typed still in it.
  *
  * What a refused submission is answered with: losing a paragraph because an
  * email address had a typo in it is the fastest way to lose a commenter.
  */
-export declare function refilledCommentForm(document: Document, values: CommentFormContext['values'], problems: CommentProblems, now?: Date, error?: string, notifiable?: boolean): CommentFormContext;
+export declare function refilledCommentForm(document: Document, values: CommentFormContext['values'], problems: CommentProblems, now: Date, error?: string, notifiable?: boolean): CommentFormContext;
 /** What a form holds before anybody has typed in it. */
 export declare function blankValues(): CommentFormContext['values'];
 /** What a submitted form typed, for putting back in a refused one. */