@geekity/cms 0.3.0 → 0.4.0

package/dist/comments/routes.js

@@ -0,0 +1,177 @@
+import { clientAddress, createLoginThrottle } from '../admin/throttle.js';
+import { isPublicDocument } from '../web/documents.js';
+import { COMMENT_NOTICE_PARAM, COMMENT_NOTICES, COMMENT_POST_PATH, commentForm, refilledCommentForm, valuesOf, } from './form.js';
+import { commentPolicyOf, commentsOpen } from './policy.js';
+import { commentAnchor } from '../web/conversation.js';
+import { COMMENT_FIELDS, COMMENT_RATE_LIMIT, COMMENT_RATE_WINDOW_SECONDS, submitComment, } from './submission.js';
+/**
+ * The one public endpoint comments add: where the form under a post posts to.
+ *
+ * It is a single path rather than one per post because the post is a field of
+ * the form. That keeps it out of the way of every permalink a site might ever
+ * mint — a path under `/_geekity/` is the CMS's own, like the health check —
+ * and means the route table does not grow with the site.
+ *
+ * Everything it answers is either a redirect or the post's own page rendered
+ * again with the form still filled in. There is no JSON, no fragment and no
+ * script: a comment form has worked without JavaScript since 2003 and there is
+ * no reason for this one to stop.
+ */
+export { COMMENT_POST_PATH, COMMENT_REPLY_PARAM } from './form.js';
+/** Register the comment endpoint. Mounted by the public site. */
+export function mountComments(app) {
+    // One limiter for the whole mount, built on the first submission because the
+    // clock is on the context. It holds nothing but recent submissions, so it
+    // belongs to the process rather than the database: a restart clears it,
+    // which is the right trade for state an anonymous caller can create.
+    let limiter;
+    function throttle(config) {
+        limiter ??= createLoginThrottle({
+            attempts: COMMENT_RATE_LIMIT,
+            lockoutSeconds: COMMENT_RATE_WINDOW_SECONDS,
+            now: config.now,
+        });
+        return limiter;
+    }
+    app.post(COMMENT_POST_PATH, async (c) => {
+        const { store, admin, renderer, config } = c.var;
+        const body = await c.req.parseBody();
+        const form = formOf(body);
+        const document = store.getBySlug(form.post);
+        if (document === undefined || !isPublicDocument(document, store.now())) {
+            return c.text('There is no such post to comment on.', 404);
+        }
+        const now = config.now();
+        if (!commentsOpen(document, commentPolicyOf(renderer.site()), now)) {
+            // 403 rather than 404: the post is there, and the reader can see for
+            // themselves that it is. Saying so is more honest than pretending the
+            // URL is wrong, and a closed post is a state rather than a mistake.
+            return page(c, document, 403, {
+                ...refilledCommentForm(document, valuesOf(form), {}, now),
+                error: 'This post is not taking comments any more.',
+            });
+        }
+        const outcome = await submitComment({
+            records: { admin, contentDir: config.contentDir },
+            document,
+            form,
+            dataDir: config.dataDir,
+            baseUrl: config.baseUrl,
+            checker: config.commentChecker,
+            // Who hears about what lands is the intake's to decide, and neither
+            // message is awaited: the reader is redirected now and they go out
+            // behind them (TASK-55).
+            notices: c.var.notifications,
+            address: clientAddress(c, config),
+            userAgent: c.req.header('user-agent'),
+            referrer: c.req.header('referer'),
+            throttle: throttle(config),
+            // Whether the box on the form meant anything, read per submission so a
+            // credential saved a moment ago is honoured now (TASK-55).
+            notifiable: c.var.mail.configured(),
+            now,
+        });
+        if (outcome.kind === 'stored') {
+            const stored = outcome.comment;
+            // A redirect rather than a rendered page, so a refresh does not post the
+            // comment a second time. An approved comment is on the page already, so
+            // the reader is sent to it; one waiting for a moderator has nothing to
+            // point at, so the reader is sent to the form they just used.
+            const anchor = stored.status === 'approved' ? commentAnchor(stored.id) : 'respond';
+            const notice = stored.status === 'approved' ? 'posted' : 'pending';
+            return c.redirect(`${document.permalink}?${COMMENT_NOTICE_PARAM}=${notice}#${anchor}`, 303);
+        }
+        const refusal = outcome.refusal;
+        if (refusal.kind === 'discarded') {
+            // Nothing is said about why. A robot that filled the honeypot, or that a
+            // checker recognised, learns exactly as much from this as from a
+            // successful post — which is the point of both defences.
+            return c.redirect(`${document.permalink}?${COMMENT_NOTICE_PARAM}=pending#respond`, 303);
+        }
+        if (refusal.kind === 'rate-limited') {
+            c.header('Retry-After', String(refusal.retryAfter));
+            return page(c, document, 429, {
+                ...refilledCommentForm(document, valuesOf(form), {}, now),
+                error: 'That is a lot of comments in a short time. Try again in a few minutes.',
+            });
+        }
+        const message = refusal.kind === 'too-quick'
+            ? 'That was posted faster than anybody types. Try again.'
+            : refusal.kind === 'stale'
+                ? 'That form had been open a long time. Here it is again — the words are still there.'
+                : undefined;
+        return page(c, document, 400, {
+            ...refilledCommentForm(document, valuesOf(form), problemsOf(refusal), now),
+            ...(message === undefined ? {} : { error: message }),
+        });
+    });
+}
+/** The post's own page, rendered again with this form on it. */
+function page(c, document, status, form) {
+    c.status(status);
+    return c.html(c.var.renderer.renderDocument(document, { commentForm: form }));
+}
+/** The per-field messages a refusal carries, if it carries any. */
+function problemsOf(refusal) {
+    return refusal.kind === 'invalid' ? (refusal.problems ?? {}) : {};
+}
+/**
+ * The thank-you a reader is shown after posting, from the query the redirect
+ * carried, or `undefined` when the URL says nothing.
+ *
+ * A query rather than a flash message, because a reader has no session to hang
+ * one on, and because a comment form that only works for people with cookies
+ * is not a comment form.
+ */
+export function commentNoticeFor(query) {
+    return query === undefined ? undefined : COMMENT_NOTICES[query];
+}
+/**
+ * The comment a `?reply_to=` query points at, as the theme needs it, or an
+ * empty object when the query names nothing on this post.
+ *
+ * Checked against the index rather than trusted, so a made-up id — or one from
+ * another page — cannot put a stranger's name on somebody's reply form, and so
+ * a comment waiting for a moderator cannot be discovered by guessing.
+ */
+export function commentReplyTarget(options) {
+    if (options.id === undefined || options.id === '')
+        return {};
+    const parent = options.admin.getComment(options.id);
+    if (parent === undefined || parent.slug !== options.document.slug)
+        return {};
+    if (parent.status !== 'approved')
+        return {};
+    return { commentReplyTo: parent.id, commentReplyingTo: parent.author.name };
+}
+/**
+ * The form for a post, or `undefined` when it is not taking comments.
+ *
+ * What the renderer is handed at boot. It reads the settings and the clock on
+ * every render, so a post that closed an hour ago stops offering a form on the
+ * very next request.
+ */
+export function commentFormFor(options) {
+    if (!commentsOpen(options.document, commentPolicyOf(options.site), options.now))
+        return undefined;
+    return commentForm(options.document, options.now, options.notifiable ?? false);
+}
+/** A submitted body as the form it is, every field a string. */
+function formOf(body) {
+    return {
+        post: text(body[COMMENT_FIELDS.post]),
+        name: text(body[COMMENT_FIELDS.name]),
+        email: text(body[COMMENT_FIELDS.email]),
+        url: text(body[COMMENT_FIELDS.url]),
+        body: text(body[COMMENT_FIELDS.body]),
+        inReplyTo: text(body[COMMENT_FIELDS.inReplyTo]),
+        trap: text(body[COMMENT_FIELDS.trap]),
+        loaded: text(body[COMMENT_FIELDS.loaded]),
+        notify: text(body[COMMENT_FIELDS.notify]),
+    };
+}
+/** A form field as a string. A file upload, or a missing field, is the empty one. */
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+//# sourceMappingURL=routes.js.map

package/dist/comments/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/comments/routes.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAI1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,aAAa,GACd,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEnE,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,GAAqB;IACjD,6EAA6E;IAC7E,0EAA0E;IAC1E,wEAAwE;IACxE,qEAAqE;IACrE,IAAI,OAAoC,CAAC;IAEzC,SAAS,QAAQ,CAAC,MAAsB;QACtC,OAAO,KAAK,mBAAmB,CAAC;YAC9B,QAAQ,EAAE,kBAAkB;YAC5B,cAAc,EAAE,2BAA2B;YAC3C,GAAG,EAAE,MAAM,CAAC,GAAG;SAChB,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACtC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC;QACjD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAE1B,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;YACvE,OAAO,CAAC,CAAC,IAAI,CAAC,sCAAsC,EAAE,GAAG,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YACnE,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,OAAO,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE;gBAC5B,GAAG,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC;gBACzD,KAAK,EAAE,4CAA4C;aACpD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC;YAClC,OAAO,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE;YACjD,QAAQ;YACR,IAAI;YACJ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,cAAc;YAC9B,oEAAoE;YACpE,mEAAmE;YACnE,yBAAyB;YACzB,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,aAAa;YAC5B,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC;YACjC,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC;YACrC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;YACjC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC;YAC1B,uEAAuE;YACvE,2DAA2D;YAC3D,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE;YACnC,GAAG;SACJ,CAAC,CAAC;QAEH,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAC/B,yEAAyE;YACzE,wEAAwE;YACxE,uEAAuE;YACvE,8DAA8D;YAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACnF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;YACnE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,SAAS,IAAI,oBAAoB,IAAI,MAAM,IAAI,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9F,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACjC,yEAAyE;YACzE,iEAAiE;YACjE,yDAAyD;YACzD,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,SAAS,IAAI,oBAAoB,kBAAkB,EAAE,GAAG,CAAC,CAAC;QAC1F,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACpC,CAAC,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;YACpD,OAAO,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE;gBAC5B,GAAG,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC;gBACzD,KAAK,EAAE,wEAAwE;aAChF,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GACX,OAAO,CAAC,IAAI,KAAK,WAAW;YAC1B,CAAC,CAAC,uDAAuD;YACzD,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,OAAO;gBACxB,CAAC,CAAC,oFAAoF;gBACtF,CAAC,CAAC,SAAS,CAAC;QAElB,OAAO,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE;YAC5B,GAAG,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC;YAC1E,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;SACrD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAKD,gEAAgE;AAChE,SAAS,IAAI,CACX,CAAsB,EACtB,QAAkB,EAClB,MAAqB,EACrB,IAAwB;IAExB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjB,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,mEAAmE;AACnE,SAAS,UAAU,CAAC,OAA6C;IAC/D,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAA4B,CAAC,CAAC,CAAC,EAAE,CAAC;AAChG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAyB;IACxD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAIlC;IACC,IAAI,OAAO,CAAC,EAAE,KAAK,SAAS,IAAI,OAAO,CAAC,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAE7D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,QAAQ,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7E,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,EAAE,CAAC;IAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,EAAE,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAM9B;IACC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAClG,OAAO,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC;AACjF,CAAC;AAED,gEAAgE;AAChE,SAAS,MAAM,CAAC,IAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACrC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACvC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACrC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,SAAS,IAAI,CAAC,KAAc;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC"}

package/dist/comments/submission.d.ts

@@ -0,0 +1,263 @@
+import type { PostComment } from '../admin/store.ts';
+import type { Document } from '../content/document.ts';
+import type { CommentNotices, CommentRecords } from './records.ts';
+/**
+ * What happens between somebody pressing Post and a proposed comment.
+ *
+ * Three defences run before anything is proposed, in the order that costs least
+ * and gives away least — the honeypot, the age of the form and the per-address
+ * rate limit. The first two are `forms/protection.ts`, shared with the contact
+ * form (TASK-56) so the two public forms cannot drift into different rules; the
+ * third is the same limiter the login form uses, over the commenter's address,
+ * so one machine cannot post a hundred comments while a moderator sleeps.
+ *
+ * What survives all three is handed to {@link intakeComment}, which is where
+ * every comment on this site is written whatever proposed it: the checker, the
+ * verdict-to-status rule, the file, the index and the notice all live there, so
+ * a form submission and a webmention cannot be treated by two sets of rules.
+ *
+ * The {@link CommentChecker} interface stays here because this is where it
+ * reads: it is the one seam a third-party service plugs into, everything
+ * Akismet's API asks for is on the submission it is handed, and its four
+ * answers are the four the intake understands. Nothing else in the CMS has to
+ * know such a service exists.
+ */
+export { hashClientAddress, MAXIMUM_FORM_AGE_SECONDS, MINIMUM_SUBMIT_SECONDS, } from '../forms/protection.ts';
+/** Where the salt that hides commenters' addresses lives, under `dataDir`. */
+export declare const COMMENT_SALT_FILE = "comment-salt";
+/** The fields the comment form submits. */
+export declare const COMMENT_FIELDS: {
+    /** The post being commented on, as its slug. */
+    readonly post: 'post';
+    /** The commenter's name. Required. */
+    readonly name: 'name';
+    /** Their email. Optional, and never shown. */
+    readonly email: 'email';
+    /** Their website. Optional. */
+    readonly url: 'url';
+    /** The comment itself, as Markdown. Required. */
+    readonly body: 'body';
+    /** The comment being answered, or empty for one answering the post. */
+    readonly inReplyTo: 'in_reply_to';
+    /** The honeypot, which every public form here spells the same way. */
+    readonly trap: "website";
+    /** When the form was rendered, in epoch milliseconds. */
+    readonly loaded: "loaded";
+    /**
+     * "Tell me when somebody answers this."
+     *
+     * A checkbox, so any non-empty value is a yes. It only ever means anything
+     * alongside an email address, and the form only offers it when the site can
+     * actually send mail (TASK-55).
+     */
+    readonly notify: 'notify';
+};
+/** A submitted comment form, as strings, which is what a form has. */
+export type CommentForm = Record<'post' | 'name' | 'email' | 'url' | 'body' | 'inReplyTo' | 'trap' | 'loaded' | 'notify', string>;
+/** How many comments one address may post before it has to wait. */
+export declare const COMMENT_RATE_LIMIT = 5;
+/** How long that window is, and how long the first wait after it lasts. */
+export declare const COMMENT_RATE_WINDOW_SECONDS = 600;
+/** The longest a name may be. */
+export declare const MAXIMUM_NAME_LENGTH = 80;
+/** The longest an email or a website may be. */
+export declare const MAXIMUM_URL_LENGTH = 500;
+/** The longest a comment may be, in characters. */
+export declare const MAXIMUM_BODY_LENGTH = 10000;
+/** What a form got wrong, one message per field. Empty means it is fine. */
+export type CommentProblems = Partial<Record<'name' | 'email' | 'url' | 'body', string>>;
+/**
+ * What is wrong with a submitted comment, as a person would be told it.
+ *
+ * Only the things a person can fix. The honeypot, the form's age and the rate
+ * limit are not here: none of them is the commenter's mistake, and two of them
+ * should not be explained to whoever tripped them.
+ */
+export declare function commentProblems(form: CommentForm): CommentProblems;
+/**
+ * What a checker is told a submission is.
+ *
+ * Akismet's `comment_type`, which is an open vocabulary with a handful of
+ * documented values. A checker is free to ignore it; the three here are the
+ * three this CMS can produce.
+ */
+export type SubmissionType = 
+/** Somebody filled in the comment form under a post. */
+'comment'
+/** Another site's page said it links here (TASK-51). */
+ | 'webmention'
+/** Somebody filled in the contact form on a page (TASK-56). */
+ | 'contact-form';
+/** Everything a checker is told about a comment on its way in. */
+export interface CommentSubmission {
+    /** The comment as it would be stored, before anything has judged it. */
+    comment: Omit<PostComment, 'id'>;
+    /**
+     * What this is, when it is not what the comment's `source` would say.
+     *
+     * A contact message is judged through this same seam — the rules, the fields
+     * and the answers are the ones a comment gets, and a site that named a
+     * `commentChecker` of its own meant that checker to see everything the
+     * public can post at it. But it is not a comment on a post, and Akismet has
+     * a word for what it is, so the caller names it. Absent means the comment
+     * speaks for itself: `webmention` for one, `comment` for everything else.
+     */
+    type?: SubmissionType | undefined;
+    /** The post it is on. */
+    post: {
+        /** Its slug. */
+        slug: string;
+        /** Its title, for a checker that reports to a human. */
+        title: string;
+        /** Its absolute URL, which is what Akismet calls the permalink. */
+        url: string;
+    };
+    /**
+     * Where the request came from, **unhashed**.
+     *
+     * A checker needs the address itself, and this is the only place it exists:
+     * the stored comment keeps a salted hash, because the file it lives in is
+     * published with the site.
+     */
+    address: string | undefined;
+    /** The `User-Agent` the browser sent, as it sent it. */
+    userAgent: string | undefined;
+    /** The `Referer` the browser sent, which is the page the form was on. */
+    referrer: string | undefined;
+    /** The site's public origin. */
+    baseUrl: string;
+}
+/** What a stored comment's later reclassification tells the checker. */
+export interface CommentReport {
+    /** The comment, as it now stands. */
+    comment: PostComment;
+    /** Its post's absolute URL. */
+    url: string;
+    /** The site's public origin. */
+    baseUrl: string;
+}
+/**
+ * What a checker can say.
+ *
+ * `spam` files the comment as spam, where a moderator can see it and change
+ * its mind. `discard` throws it away without storing it at all, which is what
+ * a service says about traffic so obviously mechanical that a queue of it
+ * would only be noise. `ham` is a positive opinion and lets the comment
+ * through even where the site would have held it. `unknown` is no opinion, and
+ * is what a checker that could not be reached should return.
+ */
+export type CommentVerdict = 'spam' | 'discard' | 'ham' | 'unknown';
+/**
+ * A third-party opinion on comments: the one seam anything like Akismet plugs
+ * into.
+ *
+ * A site names one as `commentChecker` in its config, and nothing else in the
+ * CMS knows the service exists. The two report methods are optional and are
+ * called when a moderator disagrees with what happened — marking an approved
+ * comment as spam, or letting one out of the spam list — because that
+ * correction is the only training signal such a service gets.
+ */
+export interface CommentChecker {
+    /** Judge a comment on its way in. */
+    check(submission: CommentSubmission): CommentVerdict | Promise<CommentVerdict>;
+    /** Told when a moderator files something as spam. */
+    reportSpam?(report: CommentReport): void | Promise<void>;
+    /** Told when a moderator says something was not spam after all. */
+    reportHam?(report: CommentReport): void | Promise<void>;
+}
+/** Why a submission did not become a comment. */
+export type CommentRefusal = 
+/** The form said something a person can put right. */
+{
+    kind: 'invalid';
+    problems: CommentProblems;
+}
+/** The form was submitted faster than a person types. */
+ | {
+    kind: 'too-quick';
+}
+/** The form was rendered too long ago to still be one. */
+ | {
+    kind: 'stale';
+}
+/** This address has posted enough for now. `retryAfter` is in seconds. */
+ | {
+    kind: 'rate-limited';
+    retryAfter: number;
+}
+/** The honeypot was filled in, or a checker said to throw it away. */
+ | {
+    kind: 'discarded';
+};
+/** What became of a submission. */
+export type CommentOutcome = {
+    kind: 'stored';
+    comment: PostComment;
+} | {
+    kind: 'refused';
+    refusal: CommentRefusal;
+};
+/** What {@link submitComment} needs around it. */
+export interface SubmitCommentOptions {
+    /** The files and the index a stored comment goes into. */
+    records: CommentRecords;
+    /** The post being commented on. */
+    document: Document;
+    /** What was submitted. */
+    form: CommentForm;
+    /** Where the site keeps the address salt. */
+    dataDir: string;
+    /** The site's public origin, for the checker and the stored links. */
+    baseUrl: string;
+    /** The checker, when the site named one. */
+    checker?: CommentChecker | undefined;
+    /** Who to tell about what lands, handed straight to the intake (TASK-55). */
+    notices?: CommentNotices | undefined;
+    /** Where the request came from, as far as the site can tell. */
+    address?: string | undefined;
+    /** The `User-Agent` header, for the checker. */
+    userAgent?: string | undefined;
+    /** The `Referer` header, for the checker. */
+    referrer?: string | undefined;
+    /** The rate limiter, kept by the mount so it outlives one request. */
+    throttle: CommentThrottle;
+    /**
+     * Whether "tell me about replies" is worth recording, which it is when the
+     * site can send mail at all (TASK-55).
+     *
+     * Read per submission rather than assumed, so a site that has just pasted a
+     * mail credential starts honouring the box on the very next comment, and one
+     * that removed the credential stops storing an intention it cannot keep.
+     */
+    notifiable?: boolean | undefined;
+    /** The clock. */
+    now?: Date | undefined;
+}
+/** The part of the login throttle a comment needs. */
+export interface CommentThrottle {
+    /** Seconds before this address may post again, or `undefined`. */
+    retryAfter(keys: readonly string[]): number | undefined;
+    /** Count one submission against it. */
+    fail(keys: readonly string[]): void;
+}
+/**
+ * Take a submitted form and, if it survives everything, store the comment.
+ *
+ * The caller has already decided that the post is open: whether a form should
+ * exist at all is {@link commentsOpen}'s question, and asking it here as well
+ * would let the two answers differ.
+ */
+export declare function submitComment(options: SubmitCommentOptions): Promise<CommentOutcome>;
+/** The keys a submission is rate limited against. */
+export declare function commentKeys(address: string | undefined): string[];
+/**
+ * A submitted website as the absolute URL it means, or `undefined` when it
+ * means none.
+ *
+ * A bare `example.com` becomes `https://example.com/`, because that is what
+ * somebody typing it meant and refusing it would be pedantry; anything whose
+ * scheme is not http or https is refused, because it is going on a page as a
+ * link.
+ */
+export declare function normalizeWebsite(value: string): string | undefined;
+//# sourceMappingURL=submission.d.ts.map

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

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