@nexpress/core 0.1.0

package/dist/community.d.ts

@@ -0,0 +1,1425 @@
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { F as NpPrincipal, e as NpAuthUser } from './types-TlsbXS0T.js';
+
+/**
+ * Community role registry. Maps a role name + scope type to the
+ * capabilities a grant of that role unlocks. Plugins extend the registry
+ * via `registerCommunityRole(...)` (gated by the `members:write` or
+ * `community:moderate` capability — enforced at registration time, not
+ * here).
+ *
+ * The capability vocabulary is the single source of truth for "what
+ * actions exist in the community." `memberCan()` (../community/can.ts)
+ * looks up grants and matches their roles' capability lists against the
+ * requested action.
+ */
+type CommunityScope = "site" | "category" | "collection" | "thread";
+/**
+ * Action vocabulary. Adding new actions later is fine, but rename with
+ * care — built-in role definitions reference these literals and a
+ * silent typo widens permissions instead of narrowing them.
+ */
+type CommunityCapability = "hide-comment" | "restore-comment" | "edit-any-comment" | "delete-any-comment" | "hide-thread" | "restore-thread" | "lock-thread" | "unlock-thread" | "pin-thread" | "unpin-thread" | "edit-any-thread" | "delete-any-thread" | "edit-own-thread" | "lock-own-thread" | "ban-member" | "unban-member" | "resolve-report" | "manage-category" | "view-staff-tools";
+interface CommunityRoleDefinition {
+    /** e.g. `"category-mod"`. Plugins can ship custom roles like `"tag-mod"`. */
+    role: string;
+    /** What kind of scope a grant of this role applies to. */
+    scopeType: CommunityScope;
+    /** Capabilities a grant of this role unlocks within its scope. */
+    capabilities: readonly CommunityCapability[];
+    /**
+     * Human-readable label for admin UIs that surface a role picker. Falls
+     * back to `role` when omitted.
+     */
+    label?: string;
+    /** Optional plugin id that registered this role; null for built-ins. */
+    source?: string;
+}
+/**
+ * Plugins call this from setup() to add their own role kinds. Throws
+ * when the (role, scopeType) pair is already registered to keep the
+ * registry deterministic — a plugin overriding a built-in role would
+ * silently widen permissions and is almost always a mistake.
+ */
+declare function registerCommunityRole(definition: CommunityRoleDefinition): void;
+/** Look up a role by `(role, scopeType)`. Returns undefined when unknown. */
+declare function getCommunityRole(role: string, scopeType: CommunityScope): CommunityRoleDefinition | undefined;
+/**
+ * Returns every role currently registered, built-ins first then
+ * plugin-defined. Used by the admin role picker to render selectable
+ * options for a given scope.
+ */
+declare function listCommunityRoles(scopeType?: CommunityScope): CommunityRoleDefinition[];
+/** Tests reset state between cases; production callers should never need this. */
+declare function resetCommunityRoles(): void;
+
+/**
+ * Throws `NpForbiddenError` if the member is currently banned for any
+ * scope in the chain. Used at the top of community write services
+ * before any DB mutation. Pre-existing `memberCan` enforces the same
+ * rule for permission-based actions; this helper is the catch-all
+ * for write paths that don't go through capability checks.
+ */
+declare function assertNotBanned(memberId: string, scopes?: ReadonlyArray<{
+    type: CommunityScope;
+    id: string;
+}>): Promise<void>;
+/**
+ * Structural enforcement of the ban-check gate (#311). Every
+ * community write service should run inside this wrapper — the ban
+ * check fires before `fn` and a service author can't accidentally
+ * ship a new write path that skips it.
+ *
+ * Pre-validation that doesn't write (input shape, target lookup
+ * existence) can run *before* this call; the gate is specifically
+ * for the moment between "we know enough to attempt the write" and
+ * the first DB mutation.
+ *
+ * `scopes` is the same chain `assertNotBanned` accepts — pass
+ * `[{ type: "collection", id: targetType }]` for collection-scoped
+ * actions, leave empty for site-wide-only enforcement (e.g. follows,
+ * polymorphic-target reactions where no obvious scope chain exists).
+ */
+declare function withMemberWrite<T>(memberId: string, scopes: ReadonlyArray<{
+    type: CommunityScope;
+    id: string;
+}>, fn: () => Promise<T>): Promise<T>;
+/**
+ * Action a member is attempting. Most actions are real
+ * `CommunityCapability` literals — those map 1:1 to a role's
+ * capability list. The two exceptions are `"edit-own"` and
+ * `"delete-own"`, which short-circuit on ownership without consulting
+ * grants at all.
+ */
+type MemberAction = CommunityCapability | "edit-own" | "delete-own";
+/**
+ * Caller-provided context for a permission check. The caller — the
+ * comment service, a future thread service, etc. — provides the
+ * target's ownership + scope chain rather than `memberCan` looking
+ * it up via a polymorphic join. This keeps the resolver decoupled
+ * from the per-target table layout, and lets the surface evolve
+ * without touching this resolver.
+ */
+interface MemberCanTarget {
+    /** Free-form target type — `"comment" | "thread" | "reply" | "category" | "report" | "member"`. */
+    type: string;
+    /** Stable id for logs / future denial reasons. */
+    id: string;
+    /** Member id of the target's author. Required for own-action checks. */
+    ownerId?: string;
+    /**
+     * Scope chain from most specific to least specific. A reply might
+     * provide `[{ type: "thread", id: "<threadId>" }, { type: "category",
+     * id: "<categoryId>" }]`; the resolver also checks site-wide grants
+     * regardless of what's in the chain.
+     */
+    scopes?: ReadonlyArray<{
+        type: CommunityScope;
+        id: string;
+    }>;
+}
+interface MemberCanOptions {
+    /** Override the DB handle (tests). Defaults to `getDb()`. */
+    db?: NodePgDatabase<Record<string, unknown>>;
+    /** Reference time for ban/grant expiry checks. Defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Returns true when `memberId` is allowed to perform `action` on
+ * `target`. Walk order:
+ *
+ *   1. Active scoped ban → deny everything.
+ *   2. `edit-own` / `delete-own` → allow only when `target.ownerId === memberId`.
+ *   3. Site-wide grants whose role's capability list includes `action`.
+ *   4. Scoped grants matching any element of `target.scopes`, whose role
+ *      includes `action`.
+ *   5. Otherwise deny.
+ *
+ * The resolver ignores staff (`np_users`) entirely. Staff bypass is the
+ * caller's responsibility — typically `principalCan(principal, …)` at
+ * the API layer, which routes to `memberCan` only when the principal
+ * is a member.
+ */
+declare function memberCan(memberId: string, action: MemberAction, target: MemberCanTarget, options?: MemberCanOptions): Promise<boolean>;
+
+/**
+ * Pluggable anti-spam adapter. Plugins call `setSpamAdapter(adapter)`
+ * at startup; the community write path consults `getSpamAdapter()
+ * .check(text, context)` before inserting and acts on the verdict:
+ *
+ *   - `"pass"`  → write proceeds normally (status = `visible`)
+ *   - `"flag"`  → write proceeds but lands as `pending` (visible only
+ *                 to mods; appears in the report queue indirectly via
+ *                 the moderation surface)
+ *   - `"reject"` → write is refused; the caller surfaces a 400
+ *                  `NpValidationError`. Adapters may attach a `reason`
+ *                  string for the error message.
+ *
+ * Adapters are intentionally synchronous-friendly (they may also
+ * return a Promise). The framework awaits the result so adapters that
+ * call out to a network service (Akismet, OpenAI moderation, etc.)
+ * work transparently.
+ *
+ * The default adapter is "no-op pass" — every write proceeds as
+ * before. Sites that want spam protection install one explicitly.
+ */
+type NpSpamVerdictKind = "pass" | "flag" | "reject";
+interface NpSpamVerdict {
+    kind: NpSpamVerdictKind;
+    /**
+     * Optional human-readable reason. Used as the
+     * `NpValidationError` message on `reject`, surfaced to the
+     * audit log on `flag`. Don't include PII or provider error text
+     * verbatim — operators see this in logs.
+     */
+    reason?: string;
+    /**
+     * Free-form metadata the adapter wants to log alongside the
+     * verdict (model name, score, classifier id, etc.). Surfaced to
+     * the audit log; never echoed to the end user.
+     */
+    metadata?: Record<string, unknown>;
+}
+interface NpSpamCheckContext {
+    /** Member id of the author. Adapters may use this to weight by
+     *  reputation or recent infraction history. */
+    memberId: string;
+    /**
+     * Collection slug that owns the document the comment is attached
+     * to (`"posts"`, `"discussions"`, etc.) — same value as
+     * `np_comments.target_type`. The schema is polymorphic over
+     * collection, so this is the collection identifier, not a
+     * "comment vs thread" classifier.
+     */
+    targetType: string;
+    /** Document id within `targetType` — the post / discussion the
+     *  comment is attached to. */
+    targetId: string;
+    /** Parent comment id when this is a reply, otherwise null. */
+    parentId?: string | null;
+}
+interface NpSpamAdapter {
+    check(text: string, ctx: NpSpamCheckContext): NpSpamVerdict | Promise<NpSpamVerdict>;
+}
+/**
+ * Replace the global spam adapter. Call once at app boot, typically
+ * from a plugin's `setup()`. Multiple plugins competing for this slot
+ * should compose their checks behind a single `setSpamAdapter` call —
+ * the framework holds at most one adapter to keep the verdict
+ * unambiguous.
+ */
+declare function setSpamAdapter(adapter: NpSpamAdapter): void;
+declare function getSpamAdapter(): NpSpamAdapter;
+/** Reset to the default no-op adapter. Tests use this between cases. */
+declare function resetSpamAdapter(): void;
+
+/**
+ * Pluggable profanity adapter. Sister to `spam-adapter.ts`, but
+ * semantically scoped to *language* rather than *intent*: profanity
+ * adapters score the words in a piece of content, spam adapters score
+ * the likelihood that the post is unwanted commercial / abusive.
+ *
+ * Many sites want both: an off-the-shelf regex list to scrub slurs
+ * plus an ML / Akismet-style classifier for spam. Rather than force
+ * those to compose behind a single `setSpamAdapter` call, the
+ * framework holds two slots and runs profanity FIRST, then spam.
+ * Verdicts combine with the strongest-wins rule:
+ *
+ *   - any `reject` → write is refused with that adapter's reason
+ *   - any `flag`   → write proceeds as `pending` with both adapters'
+ *                    metadata aggregated for the audit row
+ *   - both `pass`  → normal write
+ *
+ * The default adapter is "no-op pass" — every write proceeds as
+ * before. Sites that want profanity protection install one
+ * explicitly, typically from a plugin's `setup()`.
+ */
+type NpProfanityVerdictKind = "pass" | "flag" | "reject";
+interface NpProfanityVerdict {
+    kind: NpProfanityVerdictKind;
+    /**
+     * Optional human-readable reason. Used as the
+     * `NpValidationError` message on `reject`, surfaced to the
+     * audit log on `flag`. Don't include the matched word verbatim
+     * if you don't want it echoed to the end user on reject.
+     */
+    reason?: string;
+    /**
+     * Free-form metadata the adapter wants to log alongside the
+     * verdict (matched categories, severity, locale, etc.). Surfaced
+     * to the audit log; never echoed to the end user.
+     */
+    metadata?: Record<string, unknown>;
+}
+interface NpProfanityCheckContext {
+    /** Member id of the author. Adapters may use this to weight
+     *  by reputation or recent infraction history. */
+    memberId: string;
+    /**
+     * Surface the content lives on. For comments this is the
+     * collection slug of the parent doc (`"posts"`, `"discussions"`,
+     * etc.); for member-authored docs, this is the same collection
+     * slug. Mirrors `NpSpamCheckContext.targetType`.
+     */
+    targetType: string;
+    /** Document id the content belongs to. Empty string for a
+     *  pre-insert doc create — adapters that key off the id should
+     *  treat empty as "new doc". */
+    targetId: string;
+    /** Parent comment id when this is a reply, otherwise null /
+     *  undefined (for doc creates). */
+    parentId?: string | null;
+}
+interface NpProfanityAdapter {
+    check(text: string, ctx: NpProfanityCheckContext): NpProfanityVerdict | Promise<NpProfanityVerdict>;
+}
+/**
+ * Replace the global profanity adapter. Call once at app boot,
+ * typically from a plugin's `setup()`. The framework holds at most
+ * one adapter; sites that want to layer multiple lists should compose
+ * them inside a single adapter (the same convention as the spam
+ * adapter).
+ */
+declare function setProfanityAdapter(adapter: NpProfanityAdapter): void;
+declare function getProfanityAdapter(): NpProfanityAdapter;
+/** Reset to the default no-op adapter. Tests use this between cases. */
+declare function resetProfanityAdapter(): void;
+
+/**
+ * Pluggable reputation-rules hook. Sites install an adapter via
+ * `setReputationAdapter()` to compute reputation deltas in response
+ * to community events; the framework then atomically applies the
+ * delta to `np_members.reputation`.
+ *
+ * Default adapter is "no-op" (every event returns 0) — existing
+ * sites' reputation values stay at zero until they opt in.
+ *
+ * Adapter is single-method by design: a tagged-union `event` is the
+ * only argument, the return value is a signed integer delta. This
+ * keeps the API surface small while letting sites encode arbitrary
+ * weighting (e.g. "+5 for a like on a comment, −10 for a moderator
+ * hide, −0 if the reactor is a brand-new account, etc.").
+ *
+ * Adapters can be sync or async — the framework awaits the result.
+ * Throwing aborts only the reputation update, not the underlying
+ * community write (fail-soft via observability hook, same pattern
+ * as the spam adapter).
+ */
+type NpReputationEvent = 
+/** A new visible comment was inserted. Flagged / hidden / deleted
+ *  comments do NOT emit this event. */
+{
+    kind: "comment.created";
+    commentId: string;
+    memberId: string;
+    targetType: string;
+    targetId: string;
+}
+/** Mod (or member with the right grant) hid a comment. Adapters
+ *  typically penalize the author. */
+ | {
+    kind: "comment.hidden";
+    commentId: string;
+    memberId: string;
+    byStaff: boolean;
+    reason?: string | null;
+}
+/** Mod-side hard delete (`staffDeleteComment`). The body is wiped;
+ *  this is harsher than `hidden` and adapters usually penalize
+ *  more. */
+ | {
+    kind: "comment.deleted";
+    commentId: string;
+    memberId: string;
+    byStaff: boolean;
+}
+/** Someone reacted to the recipient's content (comment / thread /
+ *  reply). `recipientId` is the content author; `reactorId` is the
+ *  member who clicked the reaction. Self-reactions are filtered
+ *  before the event fires. */
+ | {
+    kind: "reaction.received";
+    reactionKind: string;
+    recipientId: string;
+    reactorId: string;
+    targetType: string;
+    targetId: string;
+}
+/** Reactor undid their reaction. Symmetric to `reaction.received`;
+ *  adapters typically return the negative of the corresponding
+ *  positive delta. */
+ | {
+    kind: "reaction.removed";
+    reactionKind: string;
+    recipientId: string;
+    reactorId: string;
+    targetType: string;
+    targetId: string;
+}
+/** A member created a top-level document in a collection that
+ *  opted into `community.memberWrite.create` (Phase 9.7a). Fires
+ *  after the row + revision are persisted; adapters can credit
+ *  reputation for thread / post creation just like comments. */
+ | {
+    kind: "document.created";
+    collectionSlug: string;
+    documentId: string;
+    memberId: string;
+}
+/** Author deleted their own document (`memberWrite.delete`,
+ *  Phase 9.7b). Symmetric to `document.created`; adapters
+ *  typically debit the original credit so a member can't farm
+ *  reputation by churn-creating and deleting threads. Mod-side
+ *  deletes are NOT covered here — those go through the staff
+ *  path which doesn't emit this event. */
+ | {
+    kind: "document.deleted";
+    collectionSlug: string;
+    documentId: string;
+    memberId: string;
+};
+interface NpReputationAdapter {
+    /** Returns the integer delta to apply to the affected member's
+     *  reputation. Sign matters: positive credits, negative debits.
+     *  Non-integer values are truncated; non-finite (NaN/Infinity)
+     *  values are skipped. Returning 0 is the no-op path. */
+    apply(event: NpReputationEvent): number | Promise<number>;
+}
+declare function setReputationAdapter(adapter: NpReputationAdapter): void;
+declare function getReputationAdapter(): NpReputationAdapter;
+/** Reset to the no-op adapter. Tests use this between cases. */
+declare function resetReputationAdapter(): void;
+
+/**
+ * Calls the registered reputation adapter for `event`, then applies
+ * the returned delta to the affected member's reputation atomically:
+ *
+ *     UPDATE np_members SET reputation = reputation + $delta
+ *     WHERE id = $memberId
+ *
+ * Failure modes are intentionally fail-soft — a buggy adapter that
+ * throws, returns a non-finite value, or hits a transient DB error
+ * MUST NOT block the underlying community write (comment insert,
+ * reaction toggle, etc.). The caller's transactional state is not
+ * touched; we just log + skip.
+ */
+declare function applyReputation(memberId: string, event: NpReputationEvent): Promise<void>;
+
+/**
+ * Site-wide community settings, persisted in the generic `np_settings`
+ * table under the `community` key. Sites that never visit the admin UI
+ * inherit `DEFAULT_COMMUNITY_SETTINGS` — every read goes through
+ * `getCommunitySettings()` which merges the stored value over the
+ * defaults so adding a new field doesn't break existing installs.
+ *
+ * Validation runs on the write path only — readers trust whatever is
+ * in the table because the only writer is the admin API which
+ * pre-validates. Tests poke values directly into `np_settings` for
+ * fault-injection cases.
+ */
+/**
+ * Per-member upload quota / rate limit. `null` on either field
+ * means unlimited (the default — no quota). Both bounds count
+ * non-deleted rows on `np_media` keyed by `uploaded_by_member_id`,
+ * so admin purges (Phase 9.7l) free up quota the same way a
+ * member self-deleting their content would. Staff uploads are
+ * never gated.
+ */
+interface NpMemberUploadQuota {
+    /** Max uploads in the trailing 24h window. `null` = unlimited. */
+    perDay: number | null;
+    /** Lifetime cap on non-deleted member uploads. `null` = unlimited. */
+    total: number | null;
+}
+interface NpCommunitySettings {
+    /**
+     * Allow-list of reaction `kind` strings. Members can only add
+     * reactions whose kind is in this list; values that pass the
+     * `KIND_RE` regex but aren't in the list are rejected with a 400.
+     * Removal of an already-existing reaction is NOT gated — if a kind
+     * is removed from the list, members can still un-react it.
+     */
+    reactionKinds: string[];
+    /**
+     * When false, `/api/members/register` refuses new sign-ups with a
+     * 403. Existing members can still sign in. Sites that want
+     * invite-only flows turn this off and provision via admin tooling.
+     */
+    registrationEnabled: boolean;
+    /** Per-member upload limits. See `NpMemberUploadQuota`. */
+    memberUploadQuota: NpMemberUploadQuota;
+}
+declare const DEFAULT_COMMUNITY_SETTINGS: NpCommunitySettings;
+declare function getCommunitySettings(): Promise<NpCommunitySettings>;
+/**
+ * Validates an incoming partial patch from the admin UI. Returns the
+ * fully-merged settings object that should be persisted. Throws
+ * `NpValidationError` with field-level errors on any malformed input.
+ */
+declare function validateCommunitySettingsPatch(current: NpCommunitySettings, patch: unknown): NpCommunitySettings;
+declare function updateCommunitySettings(patch: unknown, updatedBy: string | null): Promise<NpCommunitySettings>;
+
+/**
+ * Public-facing member profile. Hand-picked from `np_members` to
+ * exclude PII (email, password hash, login attempts, reset tokens,
+ * notification prefs, plugin meta) — page authors building public
+ * surfaces (`/u/[handle]` etc.) get a safe-to-render shape without
+ * having to remember which columns are sensitive.
+ *
+ * Suspended / deleted members are filtered out — calling
+ * `getMemberProfile` for a hidden member returns `null`. The
+ * "imported" status (Phase 21 WordPress-import provisional members)
+ * IS exposed because those profiles are visible on the public site
+ * by design. Bans are a separate, scope-based concept (`np_bans`)
+ * and don't hide the profile shell — they restrict posting; the
+ * profile page itself stays reachable like Reddit / Discourse.
+ */
+interface NpMemberProfile {
+    id: string;
+    handle: string;
+    displayName: string;
+    avatarUrl: string | null;
+    bio: string | null;
+    reputation: number;
+    joinedAt: Date;
+}
+/**
+ * Fetch a public member profile by id or handle.
+ *
+ * Resolves the avatar to a public URL (via `getMediaUrl`) so the
+ * caller doesn't need to know about the storage adapter. Pass an
+ * explicit `variant` to fetch a sized avatar — defaults to
+ * `"thumbnail"` since profile cards typically render at small
+ * sizes. Pass `"original"` for the full avatar (e.g. on the
+ * profile detail page itself).
+ *
+ * Returns `null` when:
+ *  - no row matches the id / handle,
+ *  - the member's status is `suspended` or `deleted` (treat as
+ *    "not found" for public surfaces).
+ */
+declare function getMemberProfile(idOrHandle: string, options?: {
+    avatarVariant?: "original" | "thumbnail" | "small" | "medium" | "large" | (string & {});
+}): Promise<NpMemberProfile | null>;
+/**
+ * Batch variant of `getMemberProfile` for listings (discussion
+ * indexes, comment threads, follower lists, …). Single SELECT
+ * for the rows; avatar URLs resolve in parallel via `Promise.all`.
+ *
+ * The caller passes member IDs (the `memberAuthorId` /
+ * `memberId` foreign keys most listing rows already carry).
+ * Handle-based batches aren't supported — list rows that
+ * reference a handle and not an id are rare; pass IDs.
+ *
+ * Returns a `Map<id, NpMemberProfile>` with one entry per id
+ * that matched (suspended / deleted members are dropped, so the
+ * map size may be smaller than the input). Order isn't preserved
+ * because callers typically use `byId.get(row.memberId)` per row
+ * rather than a parallel array.
+ *
+ * Empty input → empty map (no DB query).
+ */
+declare function getMemberProfiles(ids: readonly string[], options?: {
+    avatarVariant?: "original" | "thumbnail" | "small" | "medium" | "large" | (string & {});
+}): Promise<Map<string, NpMemberProfile>>;
+
+/**
+ * Tiny safe markdown renderer for comment bodies. Deliberately minimal:
+ * we escape every byte first, then pattern-match a small set of inline
+ * + block constructs so the output HTML can only ever contain the
+ * limited tag set listed below. No raw HTML pass-through, ever.
+ *
+ * Supported:
+ *   - Bold        `**text**`     → `<strong>text</strong>`
+ *   - Italic      `*text*`       → `<em>text</em>`
+ *   - Inline code `` `code` ``   → `<code>code</code>`
+ *   - Code block  ``` … ```     → `<pre><code>…</code></pre>`
+ *   - Link        `[t](url)`    → `<a href="url" rel="…">t</a>`
+ *                 (URL must start with http://, https://, or mailto:)
+ *   - Paragraph break: blank line
+ *   - Hard break  single \n     → `<br/>`
+ *
+ * NOT supported (deliberate, to keep the renderer tight + safe):
+ *   raw HTML, headings, lists, blockquotes, images, tables. If a
+ *   site needs richer formatting, plug `marked` + `dompurify` here
+ *   without changing the public function shape.
+ */
+/**
+ * Render a comment body markdown source to safe HTML. Pure function;
+ * idempotent; safe to call on the write path AND on display (we still
+ * persist the rendered version to avoid re-rendering on every read).
+ */
+declare function renderCommentMarkdown(source: string): string;
+
+type CommentStatus = "visible" | "pending" | "hidden" | "deleted";
+interface NpCommentRow {
+    id: string;
+    targetType: string;
+    targetId: string;
+    parentId: string | null;
+    memberId: string;
+    bodyMd: string;
+    bodyHtml: string;
+    status: CommentStatus;
+    hiddenReason: string | null;
+    editedAt: Date | null;
+    /** Tenant the comment belongs to. Phase 18 added the column; the type was incomplete until #364. */
+    siteId: string;
+    createdAt: Date;
+    /**
+     * Phase 21.11 — author's `np_members.status` at read time.
+     * `listComments` joins against `np_members` so callers can render
+     * a `(imported)` badge without a second round trip. Older callers
+     * that don't read this field stay unaffected — the column is
+     * nullable on the type because the underlying join is `LEFT JOIN`
+     * and `createComment` returns the row before the join is wired.
+     */
+    authorStatus?: string | null;
+}
+interface NpCommentCreateInput {
+    targetType: string;
+    targetId: string;
+    parentId?: string | null;
+    memberId: string;
+    bodyMd: string;
+}
+declare function createComment(input: NpCommentCreateInput): Promise<NpCommentRow>;
+/**
+ * Comment ordering options.
+ *
+ *   - `newest`  — created_at DESC (default; matches the
+ *     surface a fresh thread should show)
+ *   - `oldest`  — created_at ASC (chronological reads)
+ *   - `top`     — reactions DESC, then created_at DESC as
+ *     tiebreaker. Useful for high-traffic threads where the
+ *     "best" comment should bubble up regardless of when
+ *     it was posted.
+ */
+type NpCommentSort = "newest" | "oldest" | "top";
+interface NpCommentListOptions {
+    /** Default 50, max 200. */
+    limit?: number;
+    /** Default 0. */
+    offset?: number;
+    /** Newest first by default. */
+    order?: NpCommentSort;
+    /** Override visibility — staff/mods may want to see hidden rows. */
+    includeHidden?: boolean;
+    /**
+     * Phase 16.1 — when set, the viewer's mute list is applied
+     * so authors they've muted disappear from the result. The
+     * filter only kicks in for the logged-in viewer; anonymous
+     * viewers see every visible comment.
+     */
+    viewerMemberId?: string;
+}
+interface NpCommentListResult {
+    comments: NpCommentRow[];
+    totalDocs: number;
+}
+declare function listComments(targetType: string, targetId: string, options?: NpCommentListOptions): Promise<NpCommentListResult>;
+interface NpCommentUpdateInput {
+    commentId: string;
+    memberId: string;
+    bodyMd: string;
+}
+declare function updateComment(input: NpCommentUpdateInput): Promise<NpCommentRow>;
+interface NpCommentDeleteInput {
+    commentId: string;
+    memberId: string;
+}
+declare function deleteComment(input: NpCommentDeleteInput): Promise<void>;
+interface NpCommentHideInput {
+    commentId: string;
+    memberId: string;
+    reason?: string | null;
+}
+declare function hideComment(input: NpCommentHideInput): Promise<void>;
+interface NpCommentRestoreInput {
+    commentId: string;
+    memberId: string;
+}
+declare function restoreComment(input: NpCommentRestoreInput): Promise<void>;
+declare function staffHideComment(commentId: string, staffUserId: string, reason?: string | null): Promise<void>;
+declare function staffRestoreComment(commentId: string, staffUserId: string): Promise<void>;
+declare function staffDeleteComment(commentId: string, staffUserId: string): Promise<void>;
+
+/**
+ * Reactions service. `kind` is gated by both:
+ *   1. `KIND_RE` — a syntactic check (lowercase token, ≤30 chars)
+ *      that runs on every add/remove call without a DB round-trip.
+ *   2. The site's reaction allow-list, persisted in
+ *      `np_settings.community.reactionKinds` and edited from the
+ *      admin community settings page. v1 ships with `["like"]` as
+ *      the only allowed kind. Removal is NOT gated against the
+ *      allow-list — if a site retires a reaction, members can still
+ *      undo their old reactions of that kind.
+ */
+declare const DEFAULT_REACTION_KINDS: readonly ["like"];
+interface NpReactionRow {
+    id: string;
+    targetType: string;
+    targetId: string;
+    memberId: string;
+    kind: string;
+    createdAt: Date;
+}
+interface NpReactToInput {
+    targetType: string;
+    targetId: string;
+    memberId: string;
+    kind: string;
+}
+/**
+ * Adds a reaction. Idempotent: if `(target_type, target_id, member_id,
+ * kind)` already exists, returns the existing row instead of bumping
+ * the unique-constraint into an error. The first time a member reacts
+ * to a comment we also fire a notification to the comment author.
+ */
+declare function addReaction(input: NpReactToInput): Promise<NpReactionRow>;
+declare function removeReaction(input: NpReactToInput): Promise<void>;
+/**
+ * Per-target counts grouped by kind. Returns `{ like: 12 }`-style
+ * objects; missing kinds are absent (caller defaults to 0).
+ */
+declare function countReactions(targetType: string, targetId: string): Promise<Record<string, number>>;
+/**
+ * Returns the kinds the given member has reacted with on a target.
+ * Used by the site UI to render the like button as toggled-on.
+ */
+declare function listMemberReactions(targetType: string, targetId: string, memberId: string): Promise<string[]>;
+/**
+ * Internal helper — assert that the target exists for the given kind.
+ * Today only `comment` is supported. The polymorphic shape leaves
+ * room for `thread` / `reply` once a thread schema lands; the forum
+ * plugin shipped without one (it reuses `np_comments` under the
+ * `discussions` collection), so widening this surface is on hold
+ * until a separate threads design.
+ */
+declare function assertReactableExists(targetType: string, targetId: string): Promise<void>;
+
+/**
+ * Follow graph service. v1 supports `member` follows; `thread` and
+ * `tag` lands when those subjects exist. Self-follow is rejected so
+ * the recommended-follows / "people you follow" reads don't have to
+ * special-case it.
+ */
+declare const SUPPORTED_TARGETS$1: readonly ["member", "thread", "tag"];
+type FollowTarget = (typeof SUPPORTED_TARGETS$1)[number];
+interface NpFollowRow {
+    id: string;
+    followerId: string;
+    targetType: string;
+    targetId: string;
+    createdAt: Date;
+}
+interface NpFollowInput {
+    followerId: string;
+    targetType: FollowTarget;
+    targetId: string;
+}
+declare function follow(input: NpFollowInput): Promise<NpFollowRow>;
+declare function unfollow(input: NpFollowInput): Promise<void>;
+declare function isFollowing(input: NpFollowInput): Promise<boolean>;
+/**
+ * "Who am I following?" — paged. Used by the site UI to populate a
+ * member's profile or settings page.
+ */
+declare function listFollowing(followerId: string, options?: {
+    targetType?: FollowTarget;
+    limit?: number;
+    offset?: number;
+}): Promise<NpFollowRow[]>;
+
+/**
+ * Per-member notification inbox. v1 is synchronous: every event that
+ * generates a notification writes a row immediately. The inbox is
+ * in-app only — email fan-out and per-member frequency preferences
+ * are out of scope for the shipped roadmap.
+ *
+ * `kind` is a free-form string. The current vocabulary:
+ *  - `comment.reply`        — your comment got a reply
+ *  - `reaction.received`    — someone reacted to your content
+ *  - `follow.received`      — someone followed you
+ * Plugins can write their own kinds; the recipient UI fans them out
+ * to whichever rendering it knows.
+ */
+interface NpNotificationRow {
+    id: string;
+    memberId: string;
+    kind: string;
+    payload: Record<string, unknown>;
+    readAt: Date | null;
+    createdAt: Date;
+}
+interface CreateNotificationInput {
+    /** The recipient — whose inbox this lands in. */
+    memberId: string;
+    kind: string;
+    payload?: Record<string, unknown>;
+    /**
+     * Phase 16.1 — the member whose action triggered the
+     * notification (e.g. the comment author, the reactor, the
+     * follower). When set, the recipient's mute list is
+     * consulted: if the recipient has muted the actor, the
+     * notification is silently dropped. Returns `null` from
+     * the call site.
+     *
+     * Optional because some kinds are actor-less (system
+     * notices, scheduled reminders).
+     */
+    actorMemberId?: string | null;
+}
+declare function createNotification(input: CreateNotificationInput): Promise<NpNotificationRow | null>;
+interface ListNotificationsOptions {
+    /** Default 50, max 200. */
+    limit?: number;
+    /** Default 0. */
+    offset?: number;
+    /** When true, returns only unread. */
+    unreadOnly?: boolean;
+}
+interface NpNotificationListResult {
+    notifications: NpNotificationRow[];
+    totalDocs: number;
+    unread: number;
+}
+declare function listNotifications(memberId: string, options?: ListNotificationsOptions): Promise<NpNotificationListResult>;
+declare function unreadNotificationCount(memberId: string): Promise<number>;
+interface MarkReadInput {
+    memberId: string;
+    notificationIds: string[];
+}
+declare function markNotificationsRead(input: MarkReadInput): Promise<number>;
+declare function markAllNotificationsRead(memberId: string): Promise<number>;
+/**
+ * Internal sanity check used by the API: throws when one principal
+ * tries to read another member's notification. Centralised here
+ * because every per-id route gets the same rule.
+ */
+declare function assertOwnsNotification(memberId: string, notificationId: string): Promise<void>;
+
+/**
+ * Unified permission check. Staff routes pass `{ kind: "staff", user }`;
+ * member routes pass `{ kind: "member", memberId }`. Staff with
+ * `admin`, `editor`, or `moderator` role short-circuit to allow all
+ * community-mod actions — they're trusted by virtue of being CMS
+ * staff. Other staff roles (author, viewer) and members fall through
+ * to the member-side resolver, which checks role grants in
+ * `np_member_roles`.
+ *
+ * `edit-own` / `delete-own` actions still require ownership even for
+ * staff — the API layer should already check ownership for self-only
+ * routes, but the ownership rule here is belt-and-braces.
+ */
+type Principal = NpPrincipal;
+declare function principalCan(principal: Principal, action: MemberAction, target: MemberCanTarget): Promise<boolean>;
+
+/**
+ * Append-only moderation audit log. Every hide / restore / ban /
+ * role-grant write goes through here so admins can later answer
+ * "who took this action and when?" without diffing application logs.
+ *
+ * Writes are best-effort: a failed audit insert MUST NOT prevent the
+ * underlying mod action from succeeding (logged via the observability
+ * hooks instead). Reads are paginated and indexed by target.
+ */
+type AuditActorKind = "staff" | "member" | "system";
+interface AuditActor {
+    kind: AuditActorKind;
+    /** Set only for `kind: "staff"`. */
+    userId?: string;
+    /** Set only for `kind: "member"`. */
+    memberId?: string;
+}
+interface RecordAuditEventInput {
+    actor: AuditActor;
+    action: string;
+    targetType?: string;
+    targetId?: string;
+    payload?: Record<string, unknown>;
+    /**
+     * Phase 17 — site this event belongs to. When omitted the
+     * writer reads `getCurrentSiteId()` so request-driven calls
+     * automatically scope to the resolving tenant. Pass `null`
+     * explicitly to record an unscoped event (super-admin
+     * cross-site action, background job).
+     */
+    siteId?: string | null;
+}
+interface AuditEventRow {
+    id: string;
+    actorKind: AuditActorKind;
+    actorUserId: string | null;
+    actorMemberId: string | null;
+    action: string;
+    targetType: string | null;
+    targetId: string | null;
+    payload: Record<string, unknown>;
+    siteId: string | null;
+    createdAt: Date;
+}
+declare function recordAuditEvent(input: RecordAuditEventInput): Promise<void>;
+interface ListAuditOptions {
+    /** Filter to audit events targeting one specific row. */
+    targetType?: string;
+    targetId?: string;
+    /** Filter to events caused by a specific actor. */
+    actorUserId?: string;
+    actorMemberId?: string;
+    /**
+     * Filter to events whose `action` matches. Common operational
+     * query: "show every ban issued this week" →
+     * `action="member.ban.issue"` plus `since`.
+     */
+    action?: string;
+    /** Lower-bound `created_at` (inclusive). */
+    since?: Date;
+    /** Upper-bound `created_at` (exclusive). */
+    until?: Date;
+    /**
+     * Phase 17 — site filter. `undefined` means "use current
+     * request's site" (the typical admin-page query). Pass an
+     * explicit string to view another site's audit log
+     * (super-admin cross-site triage). Pass `null` to skip the
+     * filter entirely (every site's events).
+     */
+    siteId?: string | null;
+    limit?: number;
+    offset?: number;
+}
+declare function listAuditEvents(options?: ListAuditOptions): Promise<{
+    events: AuditEventRow[];
+    totalDocs: number;
+}>;
+
+declare const SUPPORTED_TARGETS: readonly ["comment", "thread", "reply", "member"];
+type ReportTarget = (typeof SUPPORTED_TARGETS)[number];
+interface NpReportRow {
+    id: string;
+    reporterId: string;
+    targetType: string;
+    targetId: string;
+    reason: string;
+    resolvedAt: Date | null;
+    resolvedByUserId: string | null;
+    resolvedByMemberId: string | null;
+    resolution: string | null;
+    siteId: string;
+    createdAt: Date;
+}
+interface FileReportInput {
+    reporterId: string;
+    targetType: ReportTarget;
+    targetId: string;
+    reason: string;
+}
+/**
+ * Members file reports against a piece of community content. The
+ * reason is free-form; mods triage it via `listReports` and
+ * `resolveReport`.
+ */
+declare function fileReport(input: FileReportInput): Promise<NpReportRow>;
+interface ListReportsOptions {
+    /** Default: only unresolved. Pass `"all"` to include resolved. */
+    status?: "unresolved" | "resolved" | "all";
+    /** Filter to a specific target type. */
+    targetType?: string;
+    /**
+     * Phase 18 — site scope. `undefined` (default) → use the
+     * request resolver's site. Pass an explicit string to view
+     * another tenant's queue (super-admin) or `null` to skip
+     * the filter entirely.
+     */
+    siteId?: string | null;
+    limit?: number;
+    offset?: number;
+}
+interface ListReportsResult {
+    reports: NpReportRow[];
+    totalDocs: number;
+}
+declare function listReports(options?: ListReportsOptions): Promise<ListReportsResult>;
+interface ResolveReportInput {
+    reportId: string;
+    /** Free-form short label: e.g. `"hidden"`, `"banned"`, `"dismissed"`. */
+    resolution: string;
+    actor: Principal;
+}
+/**
+ * Marks a report resolved. Caller is responsible for taking the
+ * actual moderation action (hide, ban, etc.) — this only flips the
+ * report row and writes an audit entry.
+ */
+declare function resolveReport(input: ResolveReportInput): Promise<NpReportRow>;
+/** Cheap "is anything in the queue?" probe for the admin badge. */
+declare function unresolvedReportCount(): Promise<number>;
+
+/**
+ * Ban service. The 9.1a schema already had `np_bans`; this layer
+ * adds the issue / list / revoke flow plus audit logging.
+ *
+ * Scope rules in v1:
+ *  - `site` — issuer must be staff (admin / editor / moderator).
+ *  - `category`, `collection` — issuer must be a community-mod or
+ *    a staff mod. We don't currently verify the issuer holds the
+ *    matching scoped grant; the API layer is responsible for that
+ *    check via `principalCan` before calling `issueBan`. The audit
+ *    log records the issuer either way for forensic review.
+ */
+type BanScope = "site" | "category" | "collection";
+type BanKind = "temporary" | "permanent";
+interface NpBanRow {
+    id: string;
+    memberId: string;
+    scopeType: BanScope;
+    scopeId: string | null;
+    kind: BanKind;
+    expiresAt: Date | null;
+    reason: string | null;
+    byUserId: string | null;
+    byMemberId: string | null;
+    /** Tenant the ban belongs to. Phase 18 added the column; the type was incomplete until #364. */
+    siteId: string;
+    createdAt: Date;
+}
+interface IssueBanInput {
+    memberId: string;
+    scopeType: BanScope;
+    scopeId?: string | null;
+    kind: BanKind;
+    /** Required when `kind === "temporary"`. */
+    expiresAt?: Date | null;
+    reason?: string | null;
+    actor: Principal;
+}
+declare function issueBan(input: IssueBanInput): Promise<NpBanRow>;
+declare function listBansForMember(memberId: string): Promise<NpBanRow[]>;
+interface RevokeBanInput {
+    banId: string;
+    actor: Principal;
+}
+/**
+ * "Revoking" a ban means deleting the row outright. The audit log
+ * preserves the history (issue + revoke each leave an entry), so we
+ * don't need a soft-delete column.
+ */
+declare function revokeBan(input: RevokeBanInput): Promise<void>;
+
+/**
+ * Member role grant service. Wraps `np_member_roles` writes with
+ * registry validation, audit logging, and friendly errors for the
+ * `(member, role, scope_type, scope_id)` unique conflict that
+ * Postgres surfaces as a 23505 raw error.
+ *
+ * Read path (`memberCan` in `community/can.ts`) already filters by
+ * `expires_at IS NULL OR expires_at > now`, so an expired grant
+ * disappears from the resolver automatically — `listMemberRoleGrants`
+ * mirrors that filter so the admin UI doesn't show ghost rows.
+ *
+ * Permission gating is the API layer's job (today: admin-only). The
+ * core helpers don't re-check, so a privileged programmatic caller
+ * can grant on behalf of any actor.
+ */
+interface NpMemberRoleGrantRow {
+    id: string;
+    memberId: string;
+    role: string;
+    scopeType: CommunityScope;
+    scopeId: string | null;
+    grantedBy: string | null;
+    grantedAt: Date;
+    expiresAt: Date | null;
+    /** Tenant the grant belongs to. Phase 18 added the column; the type was incomplete until #364. */
+    siteId: string;
+}
+interface GrantMemberRoleInput {
+    memberId: string;
+    role: string;
+    scopeType: CommunityScope;
+    /** Required when `scopeType !== "site"`; ignored otherwise. */
+    scopeId?: string | null;
+    /** Optional time-boxed grant. `null` = perpetual. */
+    expiresAt?: Date | null;
+    /** Staff user issuing the grant — recorded on the row + audit. */
+    grantedByUserId: string;
+}
+declare function grantMemberRole(input: GrantMemberRoleInput): Promise<NpMemberRoleGrantRow>;
+/**
+ * List currently-active grants for a member. Mirrors the
+ * `memberCan` filter so expired rows are hidden.
+ */
+declare function listMemberRoleGrants(memberId: string): Promise<NpMemberRoleGrantRow[]>;
+interface RevokeMemberRoleInput {
+    grantId: string;
+    revokedByUserId: string;
+}
+/**
+ * Revoke = hard delete. Audit trail preserves history. Mirrors
+ * `revokeBan`'s semantic — the grant either exists and counts, or
+ * it doesn't; soft-deleted rows would only confuse the resolver.
+ */
+declare function revokeMemberRole(input: RevokeMemberRoleInput): Promise<void>;
+
+/**
+ * Aggregate result of a member content purge. Comments are
+ * counted as deleted regardless of soft-vs-hard semantic (the
+ * underlying `staffDeleteComment` is a soft delete that wipes the
+ * body). Documents are reported per-collection because the staff
+ * UI typically wants to call out "X discussions, Y posts" rather
+ * than a flat total. Media has a `skipped` bucket because
+ * `deleteMedia` refuses rows that are still referenced from a
+ * doc (`np_media_refs`) — those need to be unlinked first; the
+ * mod can re-run after the reference is gone.
+ */
+interface NpMemberPurgeResult {
+    comments: number;
+    documents: Record<string, number>;
+    media: {
+        deleted: number;
+        skipped: number;
+    };
+}
+/**
+ * Wipes everything a single member authored: comments, top-level
+ * docs in any collection that opted into `community.memberWrite`,
+ * and uploaded media. Used by the moderation tooling to clean up
+ * after a spam wave or a banned account.
+ *
+ * Failure mode is idempotent rather than atomic — if a transient
+ * error interrupts the purge mid-way, the operator re-runs and
+ * the helper skips items already removed (it always re-queries
+ * the live state before each loop). The aggregate audit event
+ * records the actual counts performed, not the intent.
+ *
+ * Out of scope (deliberately): banning, identity revocation,
+ * follower / following links, reputation reset. Each of those is
+ * a separate moderation action with its own UI; bundling them
+ * into a single "purge" hides intent.
+ */
+declare function purgeMemberContent(memberId: string, staffUser: NpAuthUser): Promise<NpMemberPurgeResult>;
+
+/**
+ * Phase 16.1 — member-to-member mute. One-directional: A
+ * muting B hides B from A's surfaces (comments, notification
+ * fan-out). B keeps posting normally.
+ *
+ * Distinct from `np_bans` (staff-issued, global write block).
+ * Mutes are always self-service: a member calls these helpers
+ * for their own mute list, never for someone else's.
+ */
+interface NpMemberMuteRow {
+    memberId: string;
+    targetId: string;
+    createdAt: Date;
+}
+interface MuteMemberInput {
+    /** The muter — the current member taking the action. */
+    memberId: string;
+    /** The muted — whose content should disappear. */
+    targetId: string;
+}
+declare function muteMember(input: MuteMemberInput): Promise<void>;
+declare function unmuteMember(input: MuteMemberInput): Promise<boolean>;
+/**
+ * `true` when `memberId` has muted `targetId` on the current
+ * site. Used by comment listing + notification fan-out to
+ * filter views and skip alerts.
+ */
+declare function isMuted(input: MuteMemberInput): Promise<boolean>;
+/**
+ * Returns the set of `targetId`s the given member has muted on
+ * the current site. Used to filter listComments output in one
+ * DB round-trip rather than `isMuted()` per row.
+ */
+declare function getMutedTargetIds(memberId: string): Promise<Set<string>>;
+interface NpMemberMuteSummary {
+    targetId: string;
+    handle: string;
+    displayName: string;
+    createdAt: string;
+}
+interface ListMutesOptions {
+    /** Default 50, max 200. */
+    limit?: number;
+}
+/**
+ * Surfaces the muter's list with the muted member's display
+ * info joined in, so the settings UI doesn't have to round-
+ * trip through `/api/members/[handle]` for every row.
+ */
+declare function listMutes(memberId: string, options?: ListMutesOptions): Promise<NpMemberMuteSummary[]>;
+
+/**
+ * Phase 16.2 — @mention extraction + notification fan-out.
+ *
+ * The mention vocabulary mirrors the handle constraint enforced
+ * during registration (`/^[a-z0-9][a-z0-9_-]{2,29}$/`). The matcher
+ * uses a negative lookbehind so `email@host.com` doesn't trigger a
+ * mention, plus a negative lookahead so `@alice-` (handle followed
+ * by a hyphen that's not part of the handle) is rejected — handles
+ * end at non-handle characters, never mid-symbol.
+ *
+ * Fan-out semantics:
+ *  - Self-mentions are skipped (the author already knows).
+ *  - Caller-supplied `exclude` set lets the comment write path
+ *    skip the parent author so they don't get both `comment.reply`
+ *    AND `comment.mention`.
+ *  - Caller-supplied `previousHandles` lets the edit path only
+ *    notify newly-added mentions (otherwise toggling a single
+ *    other word in a comment would re-notify everyone).
+ *  - Inactive / banned / deleted members are filtered out at
+ *    resolve time.
+ *  - Mute is enforced inside `createNotification` (the
+ *    recipient's mute list drops actor-keyed notifications).
+ */
+/** Source-of-truth handle pattern, kept in sync with `apps/web` register routes. */
+declare const MENTION_HANDLE_RE: RegExp;
+interface NpMentionTarget {
+    id: string;
+    handle: string;
+}
+/**
+ * Extract unique mention handles from plain text or markdown source.
+ * Order is preserved (first appearance wins) so a UI that wants to
+ * display "you mentioned @alice and @bob" gets the same order as
+ * the body text.
+ */
+declare function extractMentionHandles(source: string): string[];
+/**
+ * Walk a Lexical-shaped rich-text payload, concatenate its text
+ * nodes, and run the mention extractor over the joined result.
+ * Mirrors the search-index walker (`collections/search.ts`) so a
+ * mention split across two adjacent text spans (e.g. `@` and
+ * `alice` in different runs because of formatting toggles) still
+ * resolves correctly — text nodes are joined without separators.
+ */
+declare function extractMentionHandlesFromRichText(content: unknown): string[];
+/**
+ * Scan a collection-document data payload (the same shape passed
+ * to `createMemberDocument` / `updateMemberDocument`) and pull
+ * out every mention handle it contains. String values are scanned
+ * with the markdown extractor; object values shaped like Lexical
+ * rich text (`{ root: { children: [...] } }`) are walked. Other
+ * values are ignored.
+ *
+ * Field names are not assumed: any string or rich-text field
+ * contributes. The mention pattern is anchored to `@<handle>`
+ * with handle-shape constraints, so unrelated string fields
+ * (`category: "news"`) won't trigger false positives.
+ */
+declare function extractMentionHandlesFromDocData(data: Record<string, unknown>): string[];
+/**
+ * Resolve handles to active member ids. Inactive / banned /
+ * deleted members are filtered out so a mention of an account
+ * the site no longer wants to notify is silently dropped (rather
+ * than raising an error to the writer — the writer can't tell the
+ * difference between "typo" and "account closed", and either way
+ * the right behaviour is "no notification").
+ *
+ * Lookups are case-insensitive on the handle (the storage column
+ * stores the canonical lowercased form).
+ */
+declare function resolveMentionedMembers(handles: string[]): Promise<NpMentionTarget[]>;
+interface FanOutMentionsInput {
+    /** The author whose write triggered the fan-out. Self-mentions are skipped. */
+    actorMemberId: string;
+    /** Notification `kind` (e.g. `"comment.mention"`, `"discussion.mention"`). */
+    kind: string;
+    /**
+     * Plain text or markdown to scan. Either `source` or `content`
+     * (or both) must be provided; if both are set the handles are
+     * unioned.
+     */
+    source?: string;
+    /** Lexical-shaped rich-text JSON to scan. */
+    content?: unknown;
+    /**
+     * Collection-document data payload to scan. All string +
+     * rich-text fields contribute. Useful for the
+     * `createMemberDocument` / `updateMemberDocument` paths.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Recipients that already received a notification for this same
+     * event (e.g. the parent author got `comment.reply`). They are
+     * skipped to avoid the "two pings for one comment" pattern.
+     */
+    exclude?: ReadonlySet<string>;
+    /** Merged into the notification payload. `mentionedMemberId` is added automatically. */
+    payload?: Record<string, unknown>;
+    /**
+     * Edit path: handles that were present in the prior revision
+     * are skipped so toggling unrelated words doesn't re-notify
+     * everyone already mentioned.
+     */
+    previousHandles?: ReadonlySet<string>;
+}
+/**
+ * Fan-out mention notifications. Returns the number of
+ * notifications actually inserted (mute / inactive / self / dedup
+ * exclusions all reduce the count).
+ */
+declare function fanOutMentionNotifications(input: FanOutMentionsInput): Promise<number>;
+
+/**
+ * Phase 16.3 — per-member notification preferences.
+ *
+ * The persisted shape is a JSONB blob on `np_members.notification_prefs`
+ * so adding fields (digest cadence in 16.4, channel toggles later)
+ * stays a typescript-only change. Today we honor:
+ *
+ *   - `disabled: string[]` — kinds the member opted out of. The
+ *     `createNotification` gate consults this and silently drops
+ *     the row. Default empty (= every kind enabled).
+ *
+ * The vocabulary of `kinds` is defined here so the UI has a single
+ * source of truth — settings page renders a toggle for each entry,
+ * and the API only accepts kinds that appear in the list (so a
+ * forged client can't disable arbitrary strings to bloat the JSONB).
+ */
+interface NpNotificationKindMeta {
+    kind: string;
+    /** Short human label. */
+    label: string;
+    /** Description rendered next to the toggle. */
+    description: string;
+}
+/** Plugin-extensible registration. Idempotent on `kind`. */
+declare function registerNotificationKind(meta: NpNotificationKindMeta): void;
+/** Returns the union of builtin + plugin-registered kinds. */
+declare function listNotificationKinds(): NpNotificationKindMeta[];
+type NpDigestCadence = "off" | "daily" | "weekly";
+interface NpNotificationPrefs {
+    /** Kinds the member opted out of. Empty / missing = all kinds enabled. */
+    disabled: string[];
+    /**
+     * Phase 16.4 — email digest cadence. `off` (default) disables
+     * the digest. `daily` and `weekly` opt the member into a
+     * batched email of unread notifications, scheduled by the
+     * `notifications:sendDigest` recurring job.
+     */
+    digest: NpDigestCadence;
+    /**
+     * Set when the digest sweep last sent an email to this member.
+     * Used to scope each digest to "unread since the last send" so
+     * members aren't repeatedly emailed about the same row. Stored
+     * as ISO-8601 string in the JSONB blob; `null` for accounts
+     * that have never received a digest.
+     *
+     * Issue #218 — superseded by `lastDigestAtBySite` once a member
+     * receives a digest under the per-site fan-out path. The legacy
+     * field is preserved for forward-compat reads (single-site
+     * deploys still see + write it via the fallback chain) and as
+     * a "any digest, ever?" marker for analytics.
+     */
+    lastDigestAt: string | null;
+    /**
+     * Issue #218 — per-(site, cadence) timestamp map. Replaces the
+     * single `lastDigestAt` for multi-site deployments. Empty when
+     * the member has never received a digest under the site-scoped
+     * sweep.
+     */
+    lastDigestAtBySite: Record<string, Partial<Record<NpDigestCadence, string>>>;
+}
+declare function getMemberNotificationPrefs(memberId: string): Promise<NpNotificationPrefs>;
+interface SetMemberNotificationPrefsInput {
+    memberId: string;
+    /**
+     * Replacement deny-list. Only kinds listed in
+     * `listNotificationKinds()` are accepted; unknown strings
+     * raise NpValidationError so a forged client can't bloat the
+     * JSONB or hide future framework kinds via a stale list.
+     * Optional — when omitted the existing list is preserved.
+     */
+    disabled?: string[];
+    /**
+     * Phase 16.4 — email digest cadence. Optional; when omitted
+     * the existing setting is preserved. `off` clears the
+     * member's enrollment.
+     */
+    digest?: NpDigestCadence;
+}
+declare function setMemberNotificationPrefs(input: SetMemberNotificationPrefsInput): Promise<NpNotificationPrefs>;
+/**
+ * Phase 16.4 — bookkeeping helper called by the digest sweep
+ * after a successful email send. Stamps `lastDigestAt` so the
+ * next run scopes its query to the correct window. Read-merge
+ * to preserve other JSONB keys.
+ *
+ * Issue #218 — when a `siteId` + `cadence` pair is supplied,
+ * the per-site / per-cadence map is updated so the next sweep
+ * for that tenant scopes to the correct "since" window. The
+ * legacy single `lastDigestAt` field is also stamped for
+ * forward-compat with single-site deploys (and as a "received
+ * any digest, ever?" marker for analytics).
+ */
+declare function recordDigestSent(memberId: string, sentAt: Date, scope?: {
+    siteId: string;
+    cadence: NpDigestCadence;
+}): Promise<void>;
+/**
+ * Inbox-side gate consulted by `createNotification`. Returns
+ * `false` when the recipient explicitly opted out of `kind`.
+ * Errors fail-open (return `true`) so a transient DB blip
+ * doesn't silently swallow notifications.
+ */
+declare function isNotificationKindEnabled(memberId: string, kind: string): Promise<boolean>;
+
+/**
+ * Phase 16.4 — email digest fan-out. The `notifications:sendDigest`
+ * recurring job calls `runDigestSweep(cadence)` on a daily and a
+ * weekly schedule; the function fetches every active member who
+ * opted into that cadence, builds an inbox summary scoped to "since
+ * last digest" (falling back to the cadence window when the member
+ * has never received one), renders an email through the configured
+ * `NpEmailAdapter`, and stamps `lastDigestAt` on success.
+ *
+ * The job is idempotent enough for production use: a sweep that
+ * runs twice for the same window won't re-email members because
+ * `lastDigestAt` advances on the first send. Failures inside the
+ * loop are logged-and-continued — one stuck member doesn't block
+ * the rest of the sweep.
+ */
+interface NpDigestNotificationSummary {
+    id: string;
+    kind: string;
+    payload: Record<string, unknown>;
+    createdAt: Date;
+}
+interface NpDigestEmailContent {
+    subject: string;
+    text: string;
+    html: string;
+}
+interface BuildDigestEmailInput {
+    member: {
+        displayName: string;
+        handle: string;
+    };
+    notifications: NpDigestNotificationSummary[];
+    cadence: NpDigestCadence;
+    /** Site display name; defaults to "your site" so the noop adapter is still readable. */
+    siteName?: string;
+}
+/**
+ * Pure renderer; exposed so plugins / tests can call it without
+ * the DB read path.
+ */
+declare function buildDigestEmail(input: BuildDigestEmailInput): NpDigestEmailContent;
+interface RunDigestSweepInput {
+    cadence: "daily" | "weekly";
+    /** Defaults to `new Date()`. Tests override for determinism. */
+    now?: Date;
+    /** Site name woven into subject + body. Defaults to `"your site"`. */
+    siteName?: string;
+}
+interface RunDigestSweepResult {
+    considered: number;
+    sent: number;
+    skipped: number;
+    failed: number;
+}
+declare function runDigestSweep(input: RunDigestSweepInput): Promise<RunDigestSweepResult>;
+
+export { type AuditActor, type AuditActorKind, type AuditEventRow, type BanKind, type BanScope, type BuildDigestEmailInput, type CommentStatus, type CommunityCapability, type CommunityRoleDefinition, type CommunityScope, type CreateNotificationInput, DEFAULT_COMMUNITY_SETTINGS, DEFAULT_REACTION_KINDS, type FanOutMentionsInput, type FileReportInput, type GrantMemberRoleInput, type IssueBanInput, type ListAuditOptions, type ListMutesOptions, type ListNotificationsOptions, type ListReportsOptions, type ListReportsResult, MENTION_HANDLE_RE, type MarkReadInput, type MemberAction, type MemberCanTarget, type MuteMemberInput, type NpBanRow, type NpCommentCreateInput, type NpCommentDeleteInput, type NpCommentHideInput, type NpCommentListOptions, type NpCommentListResult, type NpCommentRestoreInput, type NpCommentRow, type NpCommentSort, type NpCommentUpdateInput, type NpCommunitySettings, type NpDigestCadence, type NpDigestEmailContent, type NpDigestNotificationSummary, type NpFollowInput, type NpFollowRow, type NpMemberMuteRow, type NpMemberMuteSummary, type NpMemberProfile, type NpMemberPurgeResult, type NpMemberRoleGrantRow, type NpMemberUploadQuota, type NpMentionTarget, type NpNotificationKindMeta, type NpNotificationListResult, type NpNotificationPrefs, type NpNotificationRow, type NpProfanityAdapter, type NpProfanityCheckContext, type NpProfanityVerdict, type NpProfanityVerdictKind, type NpReactToInput, type NpReactionRow, type NpReportRow, type NpReputationAdapter, type NpReputationEvent, type NpSpamAdapter, type NpSpamCheckContext, type NpSpamVerdict, type NpSpamVerdictKind, type Principal, type RecordAuditEventInput, type ResolveReportInput, type RevokeBanInput, type RevokeMemberRoleInput, type RunDigestSweepInput, type RunDigestSweepResult, type SetMemberNotificationPrefsInput, addReaction, applyReputation, assertNotBanned, assertOwnsNotification, assertReactableExists, buildDigestEmail, countReactions, createComment, createNotification, deleteComment, extractMentionHandles, extractMentionHandlesFromDocData, extractMentionHandlesFromRichText, fanOutMentionNotifications, fileReport, follow, getCommunityRole, getCommunitySettings, getMemberNotificationPrefs, getMemberProfile, getMemberProfiles, getMutedTargetIds, getProfanityAdapter, getReputationAdapter, getSpamAdapter, grantMemberRole, hideComment, isFollowing, isMuted, isNotificationKindEnabled, issueBan, listAuditEvents, listBansForMember, listComments, listCommunityRoles, listFollowing, listMemberReactions, listMemberRoleGrants, listMutes, listNotificationKinds, listNotifications, listReports, markAllNotificationsRead, markNotificationsRead, memberCan, muteMember, principalCan, purgeMemberContent, recordAuditEvent, recordDigestSent, registerCommunityRole, registerNotificationKind, removeReaction, renderCommentMarkdown, resetCommunityRoles, resetProfanityAdapter, resetReputationAdapter, resetSpamAdapter, resolveMentionedMembers, resolveReport, restoreComment, revokeBan, revokeMemberRole, runDigestSweep, setMemberNotificationPrefs, setProfanityAdapter, setReputationAdapter, setSpamAdapter, staffDeleteComment, staffHideComment, staffRestoreComment, unfollow, unmuteMember, unreadNotificationCount, unresolvedReportCount, updateComment, updateCommunitySettings, validateCommunitySettingsPatch, withMemberWrite };