@geekity/cms 0.3.0 → 0.5.0

package/dist/notifications/digest.js

@@ -0,0 +1,287 @@
+import path from 'node:path';
+import { listUsers } from '../admin/accounts.js';
+import { MODERATION_ACTIONS } from '../comments/moderate.js';
+import { readFileIfPresentSync, updateFileAtomically } from '../files/atomic.js';
+import { COMMENTS_NOTIFICATION } from './comments.js';
+import { moderationLink } from './links.js';
+import { DELIVERY_WINDOW_MS, isBatchedMode, notificationMode, notificationRecipients, } from './preferences.js';
+/**
+ * One message a window instead of one message a comment.
+ *
+ * TASK-55 emails every moderator the moment something enters the queue, which
+ * is right for a quiet site and wrong for a spam wave that Akismet let
+ * through. A user who has chosen `hourly` or `daily` on `/admin/users` is sent
+ * nothing when a comment arrives; instead this sends them one message per
+ * window listing everything still waiting, each item with its own approve,
+ * spam and delete links.
+ *
+ * Three decisions hold the whole thing up:
+ *
+ * - **A digest is derived, not queued.** It is built from what
+ *   `admin.listComments({ status: 'pending' })` says right now, so an item
+ *   somebody approved before the run is simply absent and there is no queue to
+ *   keep true across a restart, a crash or a `geekity rebuild`. Nothing has to
+ *   remember what it meant to send.
+ * - **The only new state is when each user was last written to**, and it lives
+ *   in `data/notification-digests.json` rather than in the database, because
+ *   decision-9 says the database may be deleted whenever the site is stopped —
+ *   and a forgotten timestamp would mean either a window silently skipped or a
+ *   digest sent twice. It is its own file rather than a field in
+ *   `data/users.json` because that file is the answer to "who may sign in",
+ *   and a timestamp the sender rewrites every hour is bookkeeping rather than
+ *   anything about the person.
+ * - **Nothing is sent for an empty queue, and an empty run records nothing.**
+ *   A user with nothing waiting is never emailed, and because their timestamp
+ *   does not move, the first thing that does arrive goes out on the very next
+ *   tick rather than waiting out a window that had nothing in it. The promise
+ *   a mode makes is "at most one message per window", and that is kept.
+ */
+/** The message a batched user gets: everything still waiting, in one. */
+export const COMMENT_DIGEST_TEMPLATE = 'comment-digest';
+/** The file, relative to `dataDir`. */
+export const DIGEST_TIMES_FILE = 'notification-digests.json';
+/** Nobody but the site's own user reads it. */
+export const DIGEST_TIMES_FILE_MODE = 0o600;
+/**
+ * How often the timer looks.
+ *
+ * A minute. The tick is not the window — each user's own mode decides whether
+ * they are due — so this only sets how promptly a window that has come up is
+ * noticed, and a minute's lag on an hourly digest is nothing while a busier
+ * tick would be a query a minute for no one.
+ */
+export const DIGEST_TICK_MS = 60 * 1000;
+/**
+ * The most items one digest lists.
+ *
+ * A cap rather than "everything", because "everything" during a spam wave is a
+ * message with thousands of entries and three signed links each, which no mail
+ * provider would take and nobody could read. What is over the cap is counted
+ * in a line at the bottom pointing at the moderation queue, and the next
+ * window lists the next hundred.
+ */
+export const DIGEST_MAX_ITEMS = 100;
+/** Where the digest times live for a given data directory. */
+export function digestTimesFile(dataDir) {
+    return path.join(dataDir, DIGEST_TIMES_FILE);
+}
+/**
+ * When each user last had a digest of each event, as
+ * `{ [event]: { [userId]: instant } }`.
+ *
+ * Keyed by event as well as by user because the registry may grow a second
+ * batched notice, and the two would then be on windows of their own. A file
+ * that is missing, damaged or the wrong shape reads as nobody having had
+ * anything — the same direction {@link readCommentOptOuts} fails in, and for
+ * the same reason: the cost is a duplicate digest, and the alternative is a
+ * site whose timer throws over a stray comma.
+ */
+export function readDigestTimes(dataDir) {
+    return digestTimesIn(readFileIfPresentSync(digestTimesFile(dataDir)));
+}
+/**
+ * Write down that these users have just been sent a digest of this event.
+ *
+ * The read is inside the write, so two runs at once cannot lose one another's
+ * timestamps.
+ */
+export async function recordDigestTimes(dataDir, event, users, at) {
+    if (users.length === 0)
+        return;
+    await updateFileAtomically(digestTimesFile(dataDir), (current) => {
+        const held = digestTimesIn(current);
+        const forEvent = { ...held[event] };
+        for (const id of users)
+            forEvent[String(id)] = at.toISOString();
+        return `${JSON.stringify({ ...held, [event]: forEvent }, null, 2)}\n`;
+    }, { mode: DIGEST_TIMES_FILE_MODE });
+}
+/** The real one. */
+export const systemNotificationTimers = {
+    set(callback, everyMs) {
+        const handle = setInterval(callback, everyMs);
+        handle.unref?.();
+        return handle;
+    },
+    clear(handle) {
+        clearInterval(handle);
+    },
+};
+/** Build the digest sender for one site. */
+export function createCommentDigest(options) {
+    const { admin, store, mail, config } = options;
+    const timers = options.timers ?? systemNotificationTimers;
+    const tickMs = options.tickMs ?? DIGEST_TICK_MS;
+    const maxItems = options.maxItems ?? DIGEST_MAX_ITEMS;
+    const logger = options.logger ?? console;
+    let handle;
+    let running = Promise.resolve();
+    /** The post an item is on, as a message names it. */
+    function postOf(comment) {
+        const document = store.getBySlug(comment.slug);
+        return {
+            title: document?.title ?? comment.slug,
+            url: absolute(comment.permalink, config.baseUrl),
+        };
+    }
+    /**
+     * One item of the digest: the comment as a message prints it, the post it is
+     * on, and its three links.
+     *
+     * The links are minted per recipient rather than once for the run, because a
+     * moderation link is spent the first time it is used: two moderators sharing
+     * one link would mean the second of them clicking a dead one.
+     */
+    function itemFor(comment, now) {
+        const context = { dataDir: config.dataDir, baseUrl: config.baseUrl, now };
+        return {
+            comment: {
+                author: comment.author.name,
+                // The website they gave, never their email: the message goes to a
+                // moderator, but it also goes through a third party's servers.
+                website: comment.author.url,
+                source: comment.source,
+                kind: comment.kind,
+                text: comment.content.markdown,
+                html: comment.content.html,
+                submitted: comment.submitted,
+                url: comment.url,
+            },
+            post: postOf(comment),
+            actions: MODERATION_ACTIONS.map((action) => ({
+                action,
+                label: action === 'approve' ? 'Approve' : action === 'spam' ? 'Spam' : 'Delete',
+                url: moderationLink(context, comment.id, action),
+            })),
+        };
+    }
+    async function send() {
+        // Asked before anything else, so a site that sends no mail never mints a
+        // signing secret it would have no use for and never writes a record of
+        // digests it did not send.
+        if (!mail.configured())
+            return 0;
+        const now = config.now();
+        // Read per run rather than held, so a record written by another process —
+        // or one restored with the rest of `data/` — is what this run goes on.
+        const sentAt = readDigestTimes(config.dataDir)[COMMENTS_NOTIFICATION] ?? {};
+        const due = notificationRecipients(listUsers(config.dataDir), COMMENTS_NOTIFICATION).filter((recipient) => {
+            const mode = notificationMode(recipient.user, COMMENTS_NOTIFICATION);
+            if (!isBatchedMode(mode))
+                return false;
+            return elapsed(sentAt[String(recipient.user.id)], now) >= DELIVERY_WINDOW_MS[mode];
+        });
+        if (due.length === 0)
+            return 0;
+        // One query for the whole run: everybody due is due the same list, because
+        // a digest is what is waiting rather than what has happened since.
+        const pending = admin.listComments({ status: 'pending' });
+        if (pending.length === 0)
+            return 0;
+        const listed = pending.slice(0, maxItems);
+        const queueUrl = absolute('/admin/comments', config.baseUrl);
+        for (const recipient of due) {
+            void mail.send({
+                to: recipient.email,
+                template: COMMENT_DIGEST_TEMPLATE,
+                data: {
+                    items: listed.map((comment) => itemFor(comment, now)),
+                    total: pending.length,
+                    more: pending.length - listed.length,
+                    mode: notificationMode(recipient.user, COMMENTS_NOTIFICATION),
+                    queueUrl,
+                },
+            });
+        }
+        // After the sends rather than before, because `send` never rejects: a
+        // message the provider refuses is retried by the mail service itself, and
+        // a run that recorded nothing would send the whole digest again next tick.
+        await recordDigestTimes(config.dataDir, COMMENTS_NOTIFICATION, due.map((recipient) => recipient.user.id), now);
+        return due.length;
+    }
+    /** One run, and the thing `settled()` waits on. */
+    function runOnce() {
+        const started = send();
+        running = started;
+        return started;
+    }
+    return {
+        async run() {
+            return await runOnce();
+        },
+        start() {
+            if (handle !== undefined)
+                return;
+            handle = timers.set(() => {
+                running = runOnce().catch((error) => {
+                    // A tick that fails is a line in the log and nothing else: the
+                    // record was not written, so the next tick tries the same window
+                    // again.
+                    logger.warn(`A comment digest could not be sent: ${messageOf(error)}`);
+                });
+            }, tickMs);
+        },
+        stop() {
+            if (handle !== undefined)
+                timers.clear(handle);
+            handle = undefined;
+        },
+        async settled() {
+            await running.catch(ignore);
+        },
+    };
+}
+/** How long ago that instant was, or `Infinity` for one that was never. */
+function elapsed(instant, now) {
+    if (instant === undefined)
+        return Number.POSITIVE_INFINITY;
+    const at = Date.parse(instant);
+    // A timestamp nobody can read is a timestamp there is no reason to trust,
+    // and treating it as "never" costs one duplicate digest at most.
+    if (Number.isNaN(at))
+        return Number.POSITIVE_INFINITY;
+    return now.getTime() - at;
+}
+/** The record a file's bytes hold. */
+function digestTimesIn(source) {
+    if (source === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return {};
+    const found = {};
+    for (const [event, times] of Object.entries(parsed)) {
+        if (typeof times !== 'object' || times === null || Array.isArray(times))
+            continue;
+        const forEvent = {};
+        for (const [id, at] of Object.entries(times)) {
+            if (typeof at === 'string' && at !== '')
+                forEvent[id] = at;
+        }
+        if (Object.keys(forEvent).length > 0)
+            found[event] = forEvent;
+    }
+    return found;
+}
+/** A site-root path as an absolute URL. */
+function absolute(pathname, baseUrl) {
+    try {
+        return new URL(pathname, baseUrl).href;
+    }
+    catch {
+        return pathname;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function ignore() {
+    // A failed run is already logged; waiting for it must not throw.
+}
+//# sourceMappingURL=digest.js.map

package/dist/notifications/digest.js.map

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

package/dist/notifications/index.d.ts

@@ -0,0 +1,13 @@
+export { COMMENT_PENDING_TEMPLATE, COMMENT_REPLY_TEMPLATE, COMMENTS_NOTIFICATION, createCommentNotifier, } from './comments.ts';
+export type { CommentNotifier, CreateCommentNotifierOptions } from './comments.ts';
+export { COMMENT_DIGEST_TEMPLATE, createCommentDigest, DIGEST_MAX_ITEMS, DIGEST_TICK_MS, DIGEST_TIMES_FILE, digestTimesFile, readDigestTimes, recordDigestTimes, systemNotificationTimers, } from './digest.ts';
+export type { CommentDigest, CreateCommentDigestOptions, DigestLogger, NotificationTimers, } from './digest.ts';
+export { MODERATE_PATH, MODERATION_TOKEN_LIFETIME_SECONDS, moderationLink, NOTIFICATION_FIELDS, UNSUBSCRIBE_ACTION, UNSUBSCRIBE_PATH, UNSUBSCRIBE_TOKEN_LIFETIME_SECONDS, unsubscribeLink, } from './links.ts';
+export type { LinkContext } from './links.ts';
+export { addCommentOptOut, COMMENT_OPTOUTS_FILE, commentOptOutsFile, hasOptedOut, readCommentOptOuts, } from './optouts.ts';
+export { DEFAULT_DELIVERY_MODE, DELIVERY_MODE_LABELS, DELIVERY_WINDOW_MS, deliveryMode, isBatchedMode, NOTIFICATION_DELIVERY_MODES, NOTIFICATION_EVENTS, notificationEvent, notificationMode, notificationRecipients, notificationSwitches, notificationWanted, withNotification, withNotificationMode, } from './preferences.ts';
+export type { NotificationDeliveryMode, NotificationEvent, NotificationSwitch, } from './preferences.ts';
+export { mountNotificationLinks } from './routes.ts';
+export { NOTIFICATION_SECRET_FILE, notificationTokenExpiry, readNotificationToken, signNotificationToken, } from './tokens.ts';
+export type { NewNotificationToken, NotificationClaim } from './tokens.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,0BAA0B,EAC1B,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EACb,iCAAiC,EACjC,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kCAAkC,EAClC,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/notifications/index.js

@@ -0,0 +1,8 @@
+export { COMMENT_PENDING_TEMPLATE, COMMENT_REPLY_TEMPLATE, COMMENTS_NOTIFICATION, createCommentNotifier, } from './comments.js';
+export { COMMENT_DIGEST_TEMPLATE, createCommentDigest, DIGEST_MAX_ITEMS, DIGEST_TICK_MS, DIGEST_TIMES_FILE, digestTimesFile, readDigestTimes, recordDigestTimes, systemNotificationTimers, } from './digest.js';
+export { MODERATE_PATH, MODERATION_TOKEN_LIFETIME_SECONDS, moderationLink, NOTIFICATION_FIELDS, UNSUBSCRIBE_ACTION, UNSUBSCRIBE_PATH, UNSUBSCRIBE_TOKEN_LIFETIME_SECONDS, unsubscribeLink, } from './links.js';
+export { addCommentOptOut, COMMENT_OPTOUTS_FILE, commentOptOutsFile, hasOptedOut, readCommentOptOuts, } from './optouts.js';
+export { DEFAULT_DELIVERY_MODE, DELIVERY_MODE_LABELS, DELIVERY_WINDOW_MS, deliveryMode, isBatchedMode, NOTIFICATION_DELIVERY_MODES, NOTIFICATION_EVENTS, notificationEvent, notificationMode, notificationRecipients, notificationSwitches, notificationWanted, withNotification, withNotificationMode, } from './preferences.js';
+export { mountNotificationLinks } from './routes.js';
+export { NOTIFICATION_SECRET_FILE, notificationTokenExpiry, readNotificationToken, signNotificationToken, } from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/notifications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAOrB,OAAO,EACL,aAAa,EACb,iCAAiC,EACjC,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kCAAkC,EAClC,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/notifications/links.d.ts

@@ -0,0 +1,60 @@
+import type { ModerationAction } from '../comments/moderate.ts';
+/**
+ * The URLs a notification puts in front of somebody, and what they cost.
+ *
+ * Both live under `/_geekity/`, like the comment endpoint and the webmention
+ * one, so no permalink a site ever mints can shadow them and the route table
+ * does not grow with the site.
+ *
+ * Each carries two things: the token, which is the whole of its authority, and
+ * a plain `action=` that says what it does. The action is in the token too and
+ * the handler refuses a link whose two halves disagree — it is in the query so
+ * that a person reading a wall of links in a message can see which is which,
+ * and so that a browser's address bar says what is about to happen.
+ */
+/** Where a moderation link lands. */
+export declare const MODERATE_PATH = "/_geekity/moderate";
+/** Where an unsubscribe link lands. */
+export declare const UNSUBSCRIBE_PATH = "/_geekity/unsubscribe";
+/** The fields both landing pages read, from the query and from the form. */
+export declare const NOTIFICATION_FIELDS: {
+    /** The signed claim. */
+    readonly token: 'token';
+    /** What the link says it does, checked against the token. */
+    readonly action: 'action';
+};
+/** The one thing an unsubscribe token is for. */
+export declare const UNSUBSCRIBE_ACTION = "unsubscribe";
+/**
+ * How long a moderation link works for.
+ *
+ * A week. Long enough that a message read on Monday is still actionable on
+ * Friday, short enough that a mailbox somebody stopped reading a year ago is
+ * not a drawer of keys to this site's comment queue. After it, the link says
+ * so and the moderation screen is one sign-in away.
+ */
+export declare const MODERATION_TOKEN_LIFETIME_SECONDS: number;
+/**
+ * How long an unsubscribe link works for.
+ *
+ * A year, which is much longer, because the two links are asking opposite
+ * questions. A stale moderation link is a small power somebody should not
+ * still have; a stale unsubscribe link is a person who pressed Stop and was
+ * told no. The second failure is worse, and the link grants nothing but the
+ * right to be left alone.
+ */
+export declare const UNSUBSCRIBE_TOKEN_LIFETIME_SECONDS: number;
+/** What every link builder needs: the secret's home and the site's origin. */
+export interface LinkContext {
+    /** Where the signing secret lives. */
+    dataDir: string;
+    /** The site's public origin; the link is read somewhere else, so it is absolute. */
+    baseUrl: string;
+    /** The clock. */
+    now: Date;
+}
+/** The link that does one thing to one comment. */
+export declare function moderationLink(context: LinkContext, commentId: string, action: ModerationAction): string;
+/** The link that stops this site writing to an address. */
+export declare function unsubscribeLink(context: LinkContext, email: string): string;
+//# sourceMappingURL=links.d.ts.map

package/dist/notifications/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/notifications/links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE;;;;;;;;;;;;GAYG;AAEH,qCAAqC;AACrC,eAAO,MAAM,aAAa,uBAAuB,CAAC;AAElD,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB;IAC9B,wBAAwB;aACxB,KAAK,EAAE,OAAO;IACd,6DAA6D;aAC7D,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX,iDAAiD;AACjD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,QAAmB,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,QAAqB,CAAC;AAErE,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,GAAG,EAAE,IAAI,CAAC;CACX;AAED,mDAAmD;AACnD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,GACvB,MAAM,CAER;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3E"}

package/dist/notifications/links.js

@@ -0,0 +1,63 @@
+import { signNotificationToken } from './tokens.js';
+/**
+ * The URLs a notification puts in front of somebody, and what they cost.
+ *
+ * Both live under `/_geekity/`, like the comment endpoint and the webmention
+ * one, so no permalink a site ever mints can shadow them and the route table
+ * does not grow with the site.
+ *
+ * Each carries two things: the token, which is the whole of its authority, and
+ * a plain `action=` that says what it does. The action is in the token too and
+ * the handler refuses a link whose two halves disagree — it is in the query so
+ * that a person reading a wall of links in a message can see which is which,
+ * and so that a browser's address bar says what is about to happen.
+ */
+/** Where a moderation link lands. */
+export const MODERATE_PATH = '/_geekity/moderate';
+/** Where an unsubscribe link lands. */
+export const UNSUBSCRIBE_PATH = '/_geekity/unsubscribe';
+/** The fields both landing pages read, from the query and from the form. */
+export const NOTIFICATION_FIELDS = {
+    /** The signed claim. */
+    token: 'token',
+    /** What the link says it does, checked against the token. */
+    action: 'action',
+};
+/** The one thing an unsubscribe token is for. */
+export const UNSUBSCRIBE_ACTION = 'unsubscribe';
+/**
+ * How long a moderation link works for.
+ *
+ * A week. Long enough that a message read on Monday is still actionable on
+ * Friday, short enough that a mailbox somebody stopped reading a year ago is
+ * not a drawer of keys to this site's comment queue. After it, the link says
+ * so and the moderation screen is one sign-in away.
+ */
+export const MODERATION_TOKEN_LIFETIME_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * How long an unsubscribe link works for.
+ *
+ * A year, which is much longer, because the two links are asking opposite
+ * questions. A stale moderation link is a small power somebody should not
+ * still have; a stale unsubscribe link is a person who pressed Stop and was
+ * told no. The second failure is worse, and the link grants nothing but the
+ * right to be left alone.
+ */
+export const UNSUBSCRIBE_TOKEN_LIFETIME_SECONDS = 365 * 24 * 60 * 60;
+/** The link that does one thing to one comment. */
+export function moderationLink(context, commentId, action) {
+    return linkTo(context, MODERATE_PATH, action, commentId, MODERATION_TOKEN_LIFETIME_SECONDS);
+}
+/** The link that stops this site writing to an address. */
+export function unsubscribeLink(context, email) {
+    return linkTo(context, UNSUBSCRIBE_PATH, UNSUBSCRIBE_ACTION, email, UNSUBSCRIBE_TOKEN_LIFETIME_SECONDS);
+}
+/** One signed link, absolute. */
+function linkTo(context, pathname, action, subject, lifetimeSeconds) {
+    const base = context.baseUrl.endsWith('/') ? context.baseUrl : `${context.baseUrl}/`;
+    const url = new URL(pathname, base);
+    url.searchParams.set(NOTIFICATION_FIELDS.action, action);
+    url.searchParams.set(NOTIFICATION_FIELDS.token, signNotificationToken(context.dataDir, { action, subject, lifetimeSeconds }, context.now));
+    return url.href;
+}
+//# sourceMappingURL=links.js.map

package/dist/notifications/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/notifications/links.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;GAYG;AAEH,qCAAqC;AACrC,MAAM,CAAC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAElD,uCAAuC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAExD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,wBAAwB;IACxB,KAAK,EAAE,OAAO;IACd,6DAA6D;IAC7D,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX,iDAAiD;AACjD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAYrE,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAC5B,OAAoB,EACpB,SAAiB,EACjB,MAAwB;IAExB,OAAO,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,iCAAiC,CAAC,CAAC;AAC9F,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,OAAoB,EAAE,KAAa;IACjE,OAAO,MAAM,CACX,OAAO,EACP,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,EACL,kCAAkC,CACnC,CAAC;AACJ,CAAC;AAED,iCAAiC;AACjC,SAAS,MAAM,CACb,OAAoB,EACpB,QAAgB,EAChB,MAAc,EACd,OAAe,EACf,eAAuB;IAEvB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,CAAC;IACrF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACpC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,GAAG,CAAC,YAAY,CAAC,GAAG,CAClB,mBAAmB,CAAC,KAAK,EACzB,qBAAqB,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAC1F,CAAC;IACF,OAAO,GAAG,CAAC,IAAI,CAAC;AAClB,CAAC"}

package/dist/notifications/optouts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The addresses this site has been told to stop writing to.
+ *
+ * A commenter who ticked "tell me about replies" and later changed their mind
+ * clicks one link and is done, without a login and without answering anything.
+ * That is the whole of what an unsubscribe has to be, and everything else here
+ * follows from it:
+ *
+ * - **Site-wide, by address.** Not per post and not per thread. Somebody who
+ *   presses Unsubscribe means "stop", and a site that then wrote to them about
+ *   a different post would have been reading the button as "stop, on this page
+ *   only". It also means one click settles every thread they are in, including
+ *   the ones they have forgotten about.
+ * - **In `data/`, not `content/`.** The list is a list of email addresses.
+ *   `content/` is published with the site and goes into git; this is written
+ *   0600 beside the password hashes, and no screen ever renders it.
+ * - **Folded to lower case.** An address is case-insensitive in practice, and
+ *   somebody who unsubscribed as `Grace@example.com` has unsubscribed.
+ *
+ * A comment keeps its `notify` flag either way. The opt-out is checked at the
+ * moment of sending, so the list is the one thing that has to be right, and
+ * nothing has to go back and rewrite comment files somebody may have in git.
+ */
+/** The file, relative to `dataDir`. */
+export declare const COMMENT_OPTOUTS_FILE = "comment-optouts.json";
+/** Nobody but the site's own user reads it. */
+export declare const COMMENT_OPTOUTS_FILE_MODE = 384;
+/** Where the list lives for a given data directory. */
+export declare function commentOptOutsFile(dataDir: string): string;
+/**
+ * Every address that has asked not to hear any more, folded to lower case.
+ *
+ * A file that is missing, damaged or not the shape it should be reads as an
+ * empty list rather than throwing. That is the wrong direction to fail in and
+ * it is chosen deliberately: the alternative is a site whose comment endpoint
+ * throws because a JSON file has a stray comma in it.
+ */
+export declare function readCommentOptOuts(dataDir: string): Set<string>;
+/** Whether this site has been told to stop writing to that address. */
+export declare function hasOptedOut(dataDir: string, email: string | null | undefined): boolean;
+/**
+ * Stop writing to an address. Returns whether it was not already on the list.
+ *
+ * The read is inside the write, so two links clicked at once cannot lose one
+ * another's address.
+ */
+export declare function addCommentOptOut(dataDir: string, email: string): Promise<boolean>;
+//# sourceMappingURL=optouts.d.ts.map

package/dist/notifications/optouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optouts.d.ts","sourceRoot":"","sources":["../../src/notifications/optouts.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,uCAAuC;AACvC,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,+CAA+C;AAC/C,eAAO,MAAM,yBAAyB,MAAQ,CAAC;AAE/C,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAE/D;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAGtF;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBvF"}

package/dist/notifications/optouts.js

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import { readFileIfPresentSync, updateFileAtomically } from '../files/atomic.js';
+/**
+ * The addresses this site has been told to stop writing to.
+ *
+ * A commenter who ticked "tell me about replies" and later changed their mind
+ * clicks one link and is done, without a login and without answering anything.
+ * That is the whole of what an unsubscribe has to be, and everything else here
+ * follows from it:
+ *
+ * - **Site-wide, by address.** Not per post and not per thread. Somebody who
+ *   presses Unsubscribe means "stop", and a site that then wrote to them about
+ *   a different post would have been reading the button as "stop, on this page
+ *   only". It also means one click settles every thread they are in, including
+ *   the ones they have forgotten about.
+ * - **In `data/`, not `content/`.** The list is a list of email addresses.
+ *   `content/` is published with the site and goes into git; this is written
+ *   0600 beside the password hashes, and no screen ever renders it.
+ * - **Folded to lower case.** An address is case-insensitive in practice, and
+ *   somebody who unsubscribed as `Grace@example.com` has unsubscribed.
+ *
+ * A comment keeps its `notify` flag either way. The opt-out is checked at the
+ * moment of sending, so the list is the one thing that has to be right, and
+ * nothing has to go back and rewrite comment files somebody may have in git.
+ */
+/** The file, relative to `dataDir`. */
+export const COMMENT_OPTOUTS_FILE = 'comment-optouts.json';
+/** Nobody but the site's own user reads it. */
+export const COMMENT_OPTOUTS_FILE_MODE = 0o600;
+/** Where the list lives for a given data directory. */
+export function commentOptOutsFile(dataDir) {
+    return path.join(dataDir, COMMENT_OPTOUTS_FILE);
+}
+/**
+ * Every address that has asked not to hear any more, folded to lower case.
+ *
+ * A file that is missing, damaged or not the shape it should be reads as an
+ * empty list rather than throwing. That is the wrong direction to fail in and
+ * it is chosen deliberately: the alternative is a site whose comment endpoint
+ * throws because a JSON file has a stray comma in it.
+ */
+export function readCommentOptOuts(dataDir) {
+    return optOutsIn(readFileIfPresentSync(commentOptOutsFile(dataDir)));
+}
+/** Whether this site has been told to stop writing to that address. */
+export function hasOptedOut(dataDir, email) {
+    if (email === null || email === undefined || email === '')
+        return false;
+    return readCommentOptOuts(dataDir).has(email.trim().toLowerCase());
+}
+/**
+ * Stop writing to an address. Returns whether it was not already on the list.
+ *
+ * The read is inside the write, so two links clicked at once cannot lose one
+ * another's address.
+ */
+export async function addCommentOptOut(dataDir, email) {
+    const wanted = email.trim().toLowerCase();
+    if (wanted === '')
+        return false;
+    let added = false;
+    await updateFileAtomically(commentOptOutsFile(dataDir), (current) => {
+        const held = optOutsIn(current);
+        added = !held.has(wanted);
+        held.add(wanted);
+        return `${JSON.stringify({ addresses: [...held].sort() }, null, 2)}\n`;
+    }, { mode: COMMENT_OPTOUTS_FILE_MODE });
+    return added;
+}
+/** The addresses a file's bytes hold. */
+function optOutsIn(source) {
+    if (source === undefined)
+        return new Set();
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return new Set();
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return new Set();
+    const listed = parsed['addresses'];
+    if (!Array.isArray(listed))
+        return new Set();
+    const found = new Set();
+    for (const entry of listed) {
+        if (typeof entry === 'string' && entry.trim() !== '')
+            found.add(entry.trim().toLowerCase());
+    }
+    return found;
+}
+//# sourceMappingURL=optouts.js.map

package/dist/notifications/optouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optouts.js","sourceRoot":"","sources":["../../src/notifications/optouts.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,uCAAuC;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAE/C,uDAAuD;AACvD,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,SAAS,CAAC,qBAAqB,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,KAAgC;IAC3E,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACxE,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAe,EAAE,KAAa;IACnE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAEhC,IAAI,KAAK,GAAG,KAAK,CAAC;IAElB,MAAM,oBAAoB,CACxB,kBAAkB,CAAC,OAAO,CAAC,EAC3B,CAAC,OAAO,EAAE,EAAE;QACV,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QAChC,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjB,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACzE,CAAC,EACD,EAAE,IAAI,EAAE,yBAAyB,EAAE,CACpC,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yCAAyC;AACzC,SAAS,SAAS,CAAC,MAA0B;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAE3C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAE7F,MAAM,MAAM,GAAI,MAAkC,CAAC,WAAW,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAE7C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}