@supersuit/artifacts 0.33.1 → 0.35.0

package/lib/artifacts/recipients.js

@@ -0,0 +1,87 @@
+// src/artifacts/recipients.ts
+// A page published with `links: per-reader` opens only through a link made for one reader. The
+// link names an opaque rid and a signature over the page and the rid, so a rid cannot be guessed
+// or carried to another page. A view is counted only from a signal the rendered page sends, and
+// that signal carries a token minted for this one render: a fetch that never runs the page (every
+// messaging app's preview fetcher) can never produce one.
+import { createHmac, randomBytes, timingSafeEqual, createHash } from 'node:crypto';
+export const RID_RE = /^[a-z0-9]{12}$/;
+const SIG_RE = /^[0-9a-f]{16}$/;
+export const RID_COOKIE_MAX_AGE = 7_776_000;
+export const VIEW_AFTER_MS = 2000;
+export const TOKEN_MAX_AGE_MS = 86_400_000;
+const ALPHA = 'abcdefghijklmnopqrstuvwxyz0123456789';
+/** A signing secret shorter than this is treated as unset by the routes: the page shuts. */
+export const RECIPIENT_SECRET_MIN = 32;
+export function usableSecret(secret) {
+    return typeof secret === 'string' && secret.length >= RECIPIENT_SECRET_MIN ? secret : undefined;
+}
+const mac = (secret, text) => {
+    // An empty key still produces a valid MAC that anyone can compute; never sign with one.
+    if (!secret)
+        throw new Error('a signing secret is required');
+    return createHmac('sha256', secret).update(text).digest('hex').slice(0, 16);
+};
+const same = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+export function newRid() {
+    const bytes = randomBytes(12);
+    let s = '';
+    for (const b of bytes)
+        s += ALPHA[b % ALPHA.length];
+    return s;
+}
+export function ridSig(secret, id, rid) {
+    return mac(secret, `${id}\n${rid}`);
+}
+export function ridLink(pageUrl, id, rid, secret) {
+    return `${pageUrl}?r=${rid}.${ridSig(secret, id, rid)}`;
+}
+export function parseRidParam(v) {
+    if (typeof v !== 'string')
+        return null;
+    const [rid, sig, extra] = v.split('.');
+    if (extra !== undefined || !RID_RE.test(rid ?? '') || !SIG_RE.test(sig ?? ''))
+        return null;
+    return { rid, sig };
+}
+export function verifyRid(secret, id, rid, sig) {
+    if (!secret || !RID_RE.test(rid) || !SIG_RE.test(sig))
+        return false;
+    return same(ridSig(secret, id, rid), sig);
+}
+export function ridCookieName(id) {
+    return `artifact_r_${id}`;
+}
+/** `<time base36>.<nonce 16 hex>.<mac 16 hex>`, minted once per server render. */
+export function mintRenderToken(secret, id, rid, now = Date.now()) {
+    const ts = now.toString(36);
+    const nonce = randomBytes(8).toString('hex');
+    return `${ts}.${nonce}.${mac(secret, `${id}\n${rid}\n${ts}\n${nonce}`)}`;
+}
+export function verifyRenderToken(secret, id, rid, token, now = Date.now()) {
+    const parts = String(token ?? '').split('.');
+    if (parts.length !== 3)
+        return { ok: false, why: 'malformed' };
+    if (!secret)
+        return { ok: false, why: 'no secret' };
+    const [ts, nonce, m] = parts;
+    if (!/^[0-9a-z]{1,12}$/.test(ts) || !SIG_RE.test(nonce) || !SIG_RE.test(m))
+        return { ok: false, why: 'malformed' };
+    if (!same(mac(secret, `${id}\n${rid}\n${ts}\n${nonce}`), m))
+        return { ok: false, why: 'not minted here' };
+    const at = parseInt(ts, 36);
+    if (!Number.isFinite(at) || now - at > TOKEN_MAX_AGE_MS || at - now > 60_000)
+        return { ok: false, why: 'expired' };
+    return { ok: true, key: createHash('sha256').update(token).digest('hex').slice(0, 32), expiresAt: at + TOKEN_MAX_AGE_MS };
+}
+export function beatKey(secret, id, rid, session) {
+    return mac(secret, `beat\n${id}\n${rid}\n${session}`);
+}
+/** Messaging apps' and search engines' preview fetchers. Apple's LinkPresentation presents as
+ *  `facebookexternalhit/1.1 Facebot Twitterbot/1.0`. A request with no user agent is treated as one. */
+export const UNFURL_AGENTS = /facebookexternalhit|facebot|twitterbot|slackbot|whatsapp|linkedinbot|discordbot|telegrambot|skypeuripreview|redditbot|applebot|googlebot|bingbot|embedly|iframely|pinterest|bitlybot|vkshare|mastodon|preview/i;
+export function isUnfurlAgent(ua) {
+    if (!ua || !ua.trim())
+        return true;
+    return UNFURL_AGENTS.test(ua);
+}

package/lib/artifacts/render.js

@@ -77,7 +77,18 @@ const VIDEO = /\.mp4(?:[?#].*)?$/i;
 /** `![caption](x.mp3)` is a clip the reader plays: an annotated conversation, a voice note, a
  *  quote heard rather than read. Native controls, and `preload="none"` so a page of clips fetches
  *  nothing until one is pressed. The alt is its caption, shown above the player. */
-const AUDIO = /\.mp3(?:[?#].*)?$/i;
+const AUDIO = /\.(mp3|m4a)(?:[?#].*)?$/i;
+/** The stored file's name, for play tracking: the last path segment before any query. */
+const mediaName = (src) => {
+    const last = src.split(/[?#]/)[0].split('/').pop() ?? '';
+    try {
+        return decodeURIComponent(last);
+    }
+    catch {
+        return last;
+    }
+};
+const SOUND = /^sound:\s*/i;
 const VIDEO_IN_MD = /\]\([^)\s]+\.mp4(?:[?#][^)]*)?\)/i;
 // A fenced block, which `links` and `notes` fences are too; mounting for those costs one
 // no-op effect and is cheaper than parsing the markdown twice to find out.
@@ -88,11 +99,15 @@ const escapeAttr = (s) => s.replace(/&/g, '&').replace(/"/g, '"').repla
 // iPhone from going full screen. No `autoplay`: VideoAutoplay starts each one as it nears the
 // screen, so a page of videos does not download them all on open.
 function InlineVideo({ src, label }) {
-    const html = `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-video muted loop playsinline preload="metadata" disablepictureinpicture class="block w-full"></video>`;
+    const name = escapeAttr(mediaName(src));
+    // `sound:` in the alt is a moment to watch: controls and sound, started by the reader.
+    const html = SOUND.test(label)
+        ? `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label.replace(SOUND, ''))}" data-artifact-media="${name}" controls playsinline preload="metadata" class="block w-full"></video>`
+        : `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-video data-artifact-media="${name}" muted loop playsinline preload="metadata" disablepictureinpicture class="block w-full"></video>`;
     return _jsx("span", { className: "my-6 block overflow-hidden rounded-lg border border-[color:var(--a-line)]", dangerouslySetInnerHTML: { __html: html } });
 }
 function InlineAudio({ src, label }) {
-    const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio controls preload="none" class="block w-full"></audio>`;
+    const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio data-artifact-media="${escapeAttr(mediaName(src))}" controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
 /** An embed block (```simulator, ```messages): the player in a frame when the host names one, its

package/lib/artifacts/resolve-digest-store.d.ts

@@ -0,0 +1,8 @@
+import type { Firestore } from 'firebase-admin/firestore';
+import { type Burst, type Digest, type ResolveDigestStore } from './resolve-digest.js';
+export declare function createResolveDigestStore(db: Firestore, base: string): ResolveDigestStore;
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export declare function createMemoryResolveDigestStore(): ResolveDigestStore & {
+    digests(): Digest[];
+    bursts(): Burst[];
+};

package/lib/artifacts/resolve-digest-store.js

@@ -0,0 +1,194 @@
+// Where resolution digests wait and are recorded (0.34.0). Beside the readers' state, per tenant:
+//
+//   <base>ResolveBursts/<page>__<emailKey>   one reader's open burst on one page; deleted when claimed
+//   <base>ResolveDigests/<burstId>           a claimed burst, frozen: pending, then sent, skipped or failed
+//   <base>ResolveStops/<page>__<emailKey>    the reader followed the stop link for that page
+//
+// Items are stored as a JSON string (`json`), as the state store does, so a quote or a body can
+// never trip Firestore's rules on nested values. Every query is single-field (Firestore indexes
+// those itself), so no composite index is needed.
+//
+// The Firestore implementation has no emulator test here; it is proven on the live host after each
+// release that changes it. The memory implementation carries the contract tests.
+import { randomUUID } from 'node:crypto';
+import { burstKey, itemsOf } from './resolve-digest.js';
+const toBurst = (key, d) => { const { json, ...rest } = d; return { key, ...rest, threads: JSON.parse(json) }; };
+const toDigest = (id, d) => { const { json, ...rest } = d; return { id, ...rest, items: JSON.parse(json) }; };
+const isDue = (b, quietBefore, maxBefore) => b.lastAt <= quietBefore || b.firstAt <= maxBefore;
+const digestOf = (b, now) => ({
+    id: b.burstId, artifactId: b.artifactId, email: b.email, name: b.name, title: b.title, url: b.url,
+    items: itemsOf(b.threads), status: 'pending', createdAt: now, leaseUntil: now, attempts: 0,
+});
+const stopId = (artifactId, key) => `${artifactId}__${key}`;
+export function createResolveDigestStore(db, base) {
+    const bursts = () => db.collection(`${base}ResolveBursts`);
+    const digests = () => db.collection(`${base}ResolveDigests`);
+    const stops = () => db.collection(`${base}ResolveStops`);
+    return {
+        async add({ artifactId, email, name, title, url, threadId, items, at }) {
+            const ref = bursts().doc(burstKey(artifactId, email));
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                const cur = snap.exists ? toBurst(ref.id, snap.data()) : null;
+                const threads = { ...(cur?.threads ?? {}), [threadId]: items };
+                const next = {
+                    burstId: cur?.burstId ?? randomUUID(), artifactId, email, name: name ?? cur?.name ?? null, title, url,
+                    firstAt: cur?.firstAt ?? at, lastAt: cur && cur.lastAt > at ? cur.lastAt : at, json: JSON.stringify(threads),
+                };
+                tx.set(ref, next);
+            });
+        },
+        async dropThread(artifactId, threadId) {
+            const docs = (await bursts().where('artifactId', '==', artifactId).get()).docs;
+            let changed = 0;
+            for (const d of docs) {
+                await db.runTransaction(async (tx) => {
+                    const snap = await tx.get(d.ref);
+                    if (!snap.exists)
+                        return;
+                    const b = toBurst(d.id, snap.data());
+                    if (!(threadId in b.threads))
+                        return;
+                    delete b.threads[threadId];
+                    changed++;
+                    if (!Object.keys(b.threads).length)
+                        tx.delete(d.ref);
+                    else
+                        tx.update(d.ref, { json: JSON.stringify(b.threads) });
+                });
+            }
+            return changed;
+        },
+        async due(quietBefore, maxBefore, limit) {
+            const [quiet, old] = await Promise.all([
+                bursts().where('lastAt', '<=', quietBefore).limit(limit).get(),
+                bursts().where('firstAt', '<=', maxBefore).limit(limit).get(),
+            ]);
+            const out = new Map();
+            for (const d of [...quiet.docs, ...old.docs])
+                out.set(d.id, toBurst(d.id, d.data()));
+            return [...out.values()].slice(0, limit);
+        },
+        async claim({ key, burstId, quietBefore, maxBefore, now }) {
+            const ref = bursts().doc(key);
+            return db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                if (!snap.exists)
+                    return null;
+                const b = toBurst(key, snap.data());
+                if (b.burstId !== burstId || !isDue(b, quietBefore, maxBefore))
+                    return null;
+                const dref = digests().doc(b.burstId);
+                if ((await tx.get(dref)).exists) {
+                    tx.delete(ref);
+                    return null;
+                }
+                const d = digestOf(b, now);
+                const { id: _id, items, ...rest } = d;
+                tx.create(dref, { ...rest, json: JSON.stringify(items) });
+                tx.delete(ref);
+                return d;
+            });
+        },
+        async pending(now, limit) {
+            // Equality only, so no composite index; the lease filter runs here. Pending is small.
+            const docs = (await digests().where('status', '==', 'pending').limit(limit * 4).get()).docs;
+            return docs.map((d) => toDigest(d.id, d.data()))
+                .filter((d) => d.leaseUntil <= now)
+                .sort((x, y) => x.createdAt.localeCompare(y.createdAt))
+                .slice(0, limit);
+        },
+        async lease(id, now, until) {
+            const ref = digests().doc(id);
+            return db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                if (!snap.exists)
+                    return null;
+                const d = toDigest(id, snap.data());
+                if (d.status !== 'pending' || d.leaseUntil > now)
+                    return null;
+                tx.update(ref, { leaseUntil: until, attempts: d.attempts + 1 });
+                return { ...d, leaseUntil: until, attempts: d.attempts + 1 };
+            });
+        },
+        async finish(id, { status, at, reason, providerId }) {
+            await digests().doc(id).update({
+                status, ...(status === 'sent' ? { sentAt: at } : {}), ...(reason ? { reason } : {}), ...(providerId ? { providerId } : {}),
+            });
+        },
+        async release(id, retryAt) {
+            await digests().doc(id).update({ leaseUntil: retryAt });
+        },
+        async stop(artifactId, key, at) {
+            await stops().doc(stopId(artifactId, key)).set({ artifactId, emailKey: key, at });
+        },
+        stopped: async (artifactId, key) => (await stops().doc(stopId(artifactId, key)).get()).exists,
+    };
+}
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export function createMemoryResolveDigestStore() {
+    const bursts = new Map();
+    const digests = new Map();
+    const stopSet = new Set();
+    return {
+        async add({ artifactId, email, name, title, url, threadId, items, at }) {
+            const key = burstKey(artifactId, email);
+            const cur = bursts.get(key);
+            bursts.set(key, {
+                key, burstId: cur?.burstId ?? randomUUID(), artifactId, email, name: name ?? cur?.name ?? null, title, url,
+                firstAt: cur?.firstAt ?? at, lastAt: cur && cur.lastAt > at ? cur.lastAt : at,
+                threads: { ...(cur?.threads ?? {}), [threadId]: structuredClone(items) },
+            });
+        },
+        async dropThread(artifactId, threadId) {
+            let changed = 0;
+            for (const b of [...bursts.values()].filter((b) => b.artifactId === artifactId && threadId in b.threads)) {
+                delete b.threads[threadId];
+                changed++;
+                if (!Object.keys(b.threads).length)
+                    bursts.delete(b.key);
+            }
+            return changed;
+        },
+        due: async (quietBefore, maxBefore, limit) => [...bursts.values()].filter((b) => isDue(b, quietBefore, maxBefore)).slice(0, limit).map((b) => structuredClone(b)),
+        async claim({ key, burstId, quietBefore, maxBefore, now }) {
+            const b = bursts.get(key);
+            if (!b || b.burstId !== burstId || !isDue(b, quietBefore, maxBefore))
+                return null;
+            bursts.delete(key);
+            if (digests.has(b.burstId))
+                return null;
+            const d = digestOf(b, now);
+            digests.set(d.id, d);
+            return structuredClone(d);
+        },
+        pending: async (now, limit) => [...digests.values()].filter((d) => d.status === 'pending' && d.leaseUntil <= now)
+            .sort((x, y) => x.createdAt.localeCompare(y.createdAt)).slice(0, limit).map((d) => structuredClone(d)),
+        async lease(id, now, until) {
+            const d = digests.get(id);
+            if (!d || d.status !== 'pending' || d.leaseUntil > now)
+                return null;
+            d.leaseUntil = until;
+            d.attempts++;
+            return structuredClone(d);
+        },
+        async finish(id, { status, at, reason, providerId }) {
+            const d = digests.get(id);
+            if (!d)
+                return;
+            d.status = status;
+            if (status === 'sent')
+                d.sentAt = at;
+            if (reason)
+                d.reason = reason;
+            if (providerId)
+                d.providerId = providerId;
+        },
+        async release(id, retryAt) { const d = digests.get(id); if (d)
+            d.leaseUntil = retryAt; },
+        async stop(artifactId, key) { stopSet.add(stopId(artifactId, key)); },
+        stopped: async (artifactId, key) => stopSet.has(stopId(artifactId, key)),
+        digests: () => [...digests.values()].map((d) => structuredClone(d)),
+        bursts: () => [...bursts.values()].map((b) => structuredClone(b)),
+    };
+}

package/lib/artifacts/resolve-digest.d.ts

@@ -0,0 +1,236 @@
+import type { CommentResolution } from './comments.js';
+import type { StateEntry } from './state-store.js';
+/** A burst closes after this long with no new resolution for that reader on that page. */
+export declare const RESOLVE_DIGEST_QUIET_MS: number;
+/** A burst that keeps growing is sent anyway once its first resolution is this old. */
+export declare const RESOLVE_DIGEST_MAX_WAIT_MS: number;
+/** A digest leased for sending and not recorded as sent is retried after this long. */
+export declare const RESOLVE_DIGEST_LEASE_MS: number;
+/** After this many attempts a digest is recorded as failed and never tried again. */
+export declare const RESOLVE_DIGEST_MAX_ATTEMPTS = 5;
+/** How much of a reader's comment, and of the passage it is pinned to, the email quotes. */
+export declare const DIGEST_BODY_CHARS = 280;
+export declare const DIGEST_QUOTE_CHARS = 160;
+/** Where the stop link lands, under the host's origin. */
+export declare const RESOLVE_DIGEST_STOP_PATH = "/api/resolve-digest/stop";
+/** What the resolve route tells a host after a thread is resolved or reopened. */
+export type ResolveEvent = {
+    artifactId: string;
+    title: string;
+    /** The page's address, e.g. https://artifacts.example.com/abc23456. */
+    url: string;
+    /** The thread: its top comment's id and every comment in it, top comment first, oldest first. */
+    thread: {
+        id: string;
+        entries: StateEntry[];
+    };
+    /** The resolution just recorded, or null when the thread was reopened. */
+    resolution: CommentResolution | null;
+    /** Who did it: a signed-in owner or admin (their email), or the publish key or a publisher pass. */
+    actor: {
+        email?: string;
+        publisher: boolean;
+    };
+    at: string;
+};
+/** One of a reader's comments in a resolved thread, as the email lists it. */
+export type DigestItem = {
+    entryId: string;
+    threadId: string;
+    /** The passage the thread is pinned to, trimmed; null for a box drawn over the page. */
+    quote: string | null;
+    /** The reader's comment, trimmed. A voice memo with no text says so. */
+    body: string;
+    note: string | null;
+    by: string;
+    resolvedAt: string;
+};
+/** A reader's open burst on one page: the threads resolved so far, waiting for the quiet window. */
+export type Burst = {
+    key: string;
+    burstId: string;
+    artifactId: string;
+    email: string;
+    name: string | null;
+    title: string;
+    url: string;
+    firstAt: string;
+    lastAt: string;
+    threads: Record<string, DigestItem[]>;
+};
+export type DigestStatus = 'pending' | 'sent' | 'skipped' | 'failed';
+/** A claimed burst, frozen: what one email says. Its id is the burst's id, and the idempotency key. */
+export type Digest = {
+    id: string;
+    artifactId: string;
+    email: string;
+    name: string | null;
+    title: string;
+    url: string;
+    items: DigestItem[];
+    status: DigestStatus;
+    createdAt: string;
+    leaseUntil: string;
+    attempts: number;
+    sentAt?: string;
+    reason?: string;
+    providerId?: string;
+};
+export interface ResolveDigestStore {
+    /** Put this thread's items into the reader's open burst on this page (replacing the thread's
+     *  earlier items, if it was resolved again), opening a burst when none is waiting. */
+    add(input: {
+        artifactId: string;
+        email: string;
+        name: string | null;
+        title: string;
+        url: string;
+        threadId: string;
+        items: DigestItem[];
+        at: string;
+    }): Promise<void>;
+    /** Take this thread out of every burst still waiting on this page (it was reopened). A burst
+     *  left with no thread is deleted. Returns how many bursts changed. */
+    dropThread(artifactId: string, threadId: string): Promise<number>;
+    /** Bursts whose last resolution is at or before `quietBefore`, or whose first is at or before
+     *  `maxBefore`. */
+    due(quietBefore: string, maxBefore: string, limit: number): Promise<Burst[]>;
+    /** Atomically turn one due burst into a pending digest and delete the burst. Null when the
+     *  burst is gone, was replaced, or is no longer due (a resolution landed since `due`). */
+    claim(input: {
+        key: string;
+        burstId: string;
+        quietBefore: string;
+        maxBefore: string;
+        now: string;
+    }): Promise<Digest | null>;
+    /** Pending digests whose lease has run out (or was never taken), oldest first. */
+    pending(now: string, limit: number): Promise<Digest[]>;
+    /** Atomically take the lease on one pending digest whose lease has run out: sets `leaseUntil`
+     *  and counts an attempt. Null when it is not pending or another run holds it. */
+    lease(id: string, now: string, until: string): Promise<Digest | null>;
+    /** Record how a leased digest ended. */
+    finish(id: string, outcome: {
+        status: Exclude<DigestStatus, 'pending'>;
+        at: string;
+        reason?: string;
+        providerId?: string;
+    }): Promise<void>;
+    /** A send failed: leave it pending, retried once `retryAt` passes. */
+    release(id: string, retryAt: string): Promise<void>;
+    /** The reader followed the stop link for this page. Keyed by `emailKey`, so no address is stored. */
+    stop(artifactId: string, emailKey: string, at: string): Promise<void>;
+    stopped(artifactId: string, emailKey: string): Promise<boolean>;
+}
+/** One email, ready for a provider. `idempotencyKey` is the same on every retry of one digest. */
+export type DigestMessage = {
+    to: string;
+    subject: string;
+    text: string;
+    html: string;
+    /** List-Unsubscribe and List-Unsubscribe-Post (RFC 8058), pointing at the stop link. */
+    headers: Record<string, string>;
+    idempotencyKey: string;
+};
+/** The host's email provider. Throw to have the digest retried on the next run. */
+export type DigestSender = (m: DigestMessage) => Promise<{
+    id?: string;
+} | void>;
+/** A stable, non-reversible key for an address, used in document ids and stop links. */
+export declare function emailKey(email: string): string;
+export declare const burstKey: (artifactId: string, email: string) => string;
+/** The notices one resolve event queues: per signed-in writer with an address, the comments in
+ *  the thread that THEY wrote. Never the person resolving, the page's owner or its admins, never
+ *  an anonymous writer, and never a comment somebody else wrote. A reopen queues nothing. Pure. */
+export declare function noticesFor(event: ResolveEvent, o?: {
+    ownerEmail?: string;
+    admins?: readonly string[];
+}): {
+    email: string;
+    name: string | null;
+    items: DigestItem[];
+}[];
+/** A digest's items in the order the email lists them: by when each thread was resolved. */
+export declare function itemsOf(threads: Record<string, DigestItem[]>): DigestItem[];
+/** `<artifactId>.<emailKey>.<signature>`: names the page and the reader (by key, not address). */
+export declare function stopToken(secret: string, artifactId: string, email: string): string;
+export declare function verifyStopToken(secret: string | undefined, token: string | null | undefined): {
+    artifactId: string;
+    emailKey: string;
+} | null;
+/** Who resolved, as a person reads it: the names on the resolutions, with "the publisher" read as
+ *  the page's owner (an agent resolving with the publish key is resolving on the owner's behalf). */
+export declare function resolverName(items: DigestItem[], fallback: string): string;
+export type ComposeOptions = {
+    /** Whose pages these are, as the email signs off: "Example Co". */
+    brandName: string;
+    /** Who "the publisher" is when an agent resolved: the owner's first name. Default `brandName`. */
+    ownerName?: string;
+    stopUrl: string;
+};
+/** The digest as an email. Plain words, no em dashes, every comment linked to its place. */
+export declare function composeDigest(d: Pick<Digest, 'name' | 'title' | 'url' | 'items'>, o: ComposeOptions): {
+    subject: string;
+    text: string;
+    html: string;
+};
+/** An address as a report shows it: enough to recognise, not enough to collect. */
+export declare function maskEmail(email: string): string;
+export type ResolveDigestOptions = {
+    store: ResolveDigestStore;
+    send: DigestSender;
+    /** Signs stop links. Read at call time. Without it nothing is queued and nothing is sent, since
+     *  every digest must carry a working stop link. */
+    secret: () => string | undefined;
+    /** The host's origin, e.g. https://artifacts.example.com. */
+    siteUrl: string;
+    brandName: string;
+    ownerName?: string;
+    /** Never notified about their own comments, like the person resolving. */
+    ownerEmail?: string;
+    admins?: readonly string[];
+    quietMs?: number;
+    maxWaitMs?: number;
+    /** The page's title for the stop page. Optional. */
+    titleOf?: (artifactId: string) => Promise<string | null>;
+    stopPath?: string;
+};
+export type FlushReport = {
+    now: string;
+    dryRun: boolean;
+    due: number;
+    claimed: number;
+    sent: {
+        id: string;
+        to: string;
+        subject: string;
+        comments: number;
+    }[];
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    /** dryRun only: what a real run would send now. */
+    wouldSend?: {
+        to: string;
+        subject: string;
+        comments: number;
+        artifactId: string;
+        stopped: boolean;
+    }[];
+};
+export declare function createResolveDigests(o: ResolveDigestOptions): {
+    onResolve: (event: ResolveEvent) => Promise<void>;
+    flush: (opts?: {
+        now?: Date;
+        dryRun?: boolean;
+        limit?: number;
+    }) => Promise<FlushReport>;
+    STOP: (req: Request) => Promise<Response>;
+    stopUrl: (artifactId: string, email: string) => string | null;
+    message: (d: Digest) => DigestMessage | null;
+};