@meith/messages 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@meith/messages",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/messages"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/core": "0.16.0",
+    "@meith/markdown": "0.16.0",
+    "@meith/i18n": "0.16.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export {
+  type Draft,
+  MESSAGES_PAGE_SIZE,
+  type MessageAudit,
+  MessageService,
+  NO_MESSAGE_AUDIT,
+  type SendInput,
+  SUPPRESSED,
+  splitNames,
+} from './service'
+export {
+  BODY_MAX,
+  type FolderCounts,
+  MAX_RECIPIENTS,
+  MESSAGE_FOLDERS,
+  MESSAGE_ROLES,
+  type MessageCopy,
+  type MessageDetail,
+  type MessageFolder,
+  type MessageListRow,
+  type MessageNotifierPort,
+  type MessageParticipant,
+  type MessagePolicy,
+  type MessageRepository,
+  type MessageRole,
+  type PrivateMessage,
+  parseFolder,
+  type ResolvedRecipient,
+  SUBJECT_MAX,
+} from './types'

package/src/service.ts

@@ -0,0 +1,425 @@
+import { ForbiddenError, NotFoundError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+import {
+  authorRef,
+  type BoardVocabulary,
+  CORE_RENDERING,
+  EMPTY_VOCABULARY,
+  type MarkdownPipeline,
+  quoteBlock,
+  renderThrough,
+  sourceAsMarkdown,
+  vocabularyOptions,
+} from '@meith/markdown'
+
+import {
+  BODY_MAX,
+  type FolderCounts,
+  MAX_RECIPIENTS,
+  type MessageDetail,
+  type MessageFolder,
+  type MessageListRow,
+  type MessageNotifierPort,
+  type MessagePolicy,
+  type MessageRepository,
+  type PrivateMessage,
+  type ResolvedRecipient,
+  SUBJECT_MAX,
+} from './types'
+
+export const MESSAGES_PAGE_SIZE = 25
+
+export interface SendInput {
+  readonly authorUserId: number
+  readonly authorUsername: string
+  readonly to: string
+  readonly bcc?: string
+  readonly subject: string
+  readonly message: string
+  readonly receiptRequested?: boolean
+  readonly replyToId?: number | null
+}
+
+export interface Draft {
+  readonly to: string
+  readonly subject: string
+  readonly message: string
+  readonly replyToId: number | null
+}
+
+/**
+ * Where a plugin sees a private message. `before` may rewrite it or return null
+ * to drop it; `sent` is told what was stored.
+ */
+export interface MessageAudit {
+  readonly before: (input: {
+    readonly senderId: number
+    readonly recipientIds: readonly number[]
+    readonly subject: string
+    readonly body: string
+  }) => Promise<{
+    readonly senderId: number
+    readonly recipientIds: readonly number[]
+    readonly subject: string
+    readonly body: string
+  } | null>
+  readonly sent: (input: {
+    readonly messageId: number
+    readonly recipientIds: readonly number[]
+  }) => Promise<void>
+}
+
+export const NO_MESSAGE_AUDIT: MessageAudit = {
+  before: async (input) => input,
+  sent: async () => {},
+}
+
+/**
+ * What `send` answers when a plugin suppressed the message. The sender is not
+ * told, which is the point: a spam filter that announces itself is a spam
+ * filter somebody tunes against.
+ */
+export const SUPPRESSED = 0
+
+export class MessageService {
+  private readonly repository: MessageRepository
+  private readonly policy: MessagePolicy
+  private readonly notifier: MessageNotifierPort | null
+  private readonly now: () => Date
+  private readonly vocabulary: () => Promise<BoardVocabulary>
+  private readonly rendering: MarkdownPipeline
+  private readonly audit: MessageAudit
+
+  constructor(deps: {
+    messages: MessageRepository
+    policy: MessagePolicy
+    notifier?: MessageNotifierPort | null
+    now?: () => Date
+    vocabulary?: () => Promise<BoardVocabulary>
+    rendering?: MarkdownPipeline
+    audit?: MessageAudit
+  }) {
+    this.repository = deps.messages
+    this.policy = deps.policy
+    this.notifier = deps.notifier ?? null
+    this.now = deps.now ?? (() => new Date())
+    this.vocabulary = deps.vocabulary ?? (async () => EMPTY_VOCABULARY)
+    this.rendering = deps.rendering ?? CORE_RENDERING
+    this.audit = deps.audit ?? NO_MESSAGE_AUDIT
+  }
+
+  async list(input: {
+    readonly userId: number
+    readonly folder: MessageFolder
+    readonly before?: number | undefined
+    readonly offset?: number | undefined
+  }): Promise<{ rows: readonly MessageListRow[]; nextBefore: number | null }> {
+    const rows = await this.repository.list({
+      userId: input.userId,
+      folder: input.folder,
+      limit: MESSAGES_PAGE_SIZE + 1,
+      before: input.before,
+      offset: input.offset,
+    })
+
+    const page = rows.slice(0, MESSAGES_PAGE_SIZE)
+    const last = page[page.length - 1]
+    return {
+      rows: page,
+      nextBefore: rows.length > MESSAGES_PAGE_SIZE && last !== undefined ? last.copyId : null,
+    }
+  }
+
+  counts(userId: number): Promise<FolderCounts> {
+    return this.repository.counts(userId)
+  }
+
+  async open(input: { messageId: number; userId: number }): Promise<MessageDetail> {
+    const detail = await this.repository.detail(input)
+    if (detail === null) throw new NotFoundError(msg('error.messages.such-message'))
+
+    const visible = this.visibleParticipants(detail, input.userId)
+
+    if (detail.copy.readAt === null && detail.copy.role !== 'author') {
+      const at = this.now()
+      await this.repository.setRead({ userId: input.userId, copyIds: [detail.copy.id], at })
+
+      if (detail.message.receiptRequested && detail.message.authorUserId !== null) {
+        await this.notify(() =>
+          this.notifier?.receiptRead({
+            userId: detail.message.authorUserId as number,
+            messageId: detail.message.id,
+            byUsername: visible.me,
+            subject: detail.message.subject,
+          }),
+        )
+      }
+
+      return { ...detail, copy: { ...detail.copy, readAt: at }, participants: visible.participants }
+    }
+
+    return { ...detail, participants: visible.participants }
+  }
+
+  private visibleParticipants(
+    detail: MessageDetail,
+    userId: number,
+  ): { participants: MessageDetail['participants']; me: string } {
+    const isAuthor = detail.message.authorUserId === userId
+    const me = detail.participants.find((p) => p.userId === userId)
+
+    return {
+      participants: detail.participants.filter(
+        (participant) => participant.role !== 'bcc' || isAuthor || participant.userId === userId,
+      ),
+      me: me?.username ?? '',
+    }
+  }
+
+  async send(input: SendInput): Promise<number> {
+    const subject = input.subject.trim()
+    const message = input.message.trim()
+
+    if (subject === '') throw new ValidationError(msg('error.messages.message-needs-subject'))
+    if (subject.length > SUBJECT_MAX) {
+      throw new ValidationError(msg('error.messages.subject-length', { max: SUBJECT_MAX }))
+    }
+    if (message === '') throw new ValidationError(msg('error.messages.message-needs-something'))
+    if (message.length > BODY_MAX) {
+      throw new ValidationError(msg('error.messages.body-length', { max: BODY_MAX }))
+    }
+
+    const resolved = await this.resolveRecipients(input)
+    await this.assertRoomFor(input.authorUserId, resolved)
+
+    const proposed = await this.audit.before({
+      senderId: input.authorUserId,
+      recipientIds: resolved.map((recipient) => recipient.userId as number),
+      subject,
+      body: message,
+    })
+    if (proposed === null) return SUPPRESSED
+
+    /*
+     * Only the recipients the board already resolved survive: a plugin may
+     * take one off the list, and cannot put one on it, because the addressees
+     * are the sender's choice and the board's check, not a plugin's.
+     */
+    const kept = new Set(proposed.recipientIds)
+    const recipients = resolved.filter((recipient) => kept.has(recipient.userId as number))
+    if (recipients.length === 0) return SUPPRESSED
+
+    const vocabulary = await this.vocabulary()
+    const rendered = await renderThrough(
+      this.rendering,
+      proposed.body,
+      { source: 'pm', viewer: authorRef(input.authorUserId) },
+      vocabularyOptions(vocabulary),
+    )
+    const at = this.now()
+
+    const messageId = await this.repository.send({
+      authorUserId: input.authorUserId,
+      authorUsername: input.authorUsername,
+      subject: proposed.subject,
+      message: proposed.body,
+      messageHtml: rendered.html,
+      renderVersion: rendered.version,
+      vocabVersion: vocabulary.revision,
+      replyToId: input.replyToId ?? null,
+      receiptRequested: input.receiptRequested === true,
+      recipients: recipients.map((r) => ({ userId: r.userId as number, bcc: r.bcc })),
+      at,
+    })
+
+    await this.audit.sent({
+      messageId,
+      recipientIds: recipients.map((recipient) => recipient.userId as number),
+    })
+
+    for (const recipient of recipients) {
+      await this.notify(() =>
+        this.notifier?.messageReceived({
+          userId: recipient.userId as number,
+          messageId,
+          fromUsername: input.authorUsername,
+          subject: proposed.subject,
+        }),
+      )
+    }
+
+    return messageId
+  }
+
+  private async resolveRecipients(input: SendInput): Promise<readonly ResolvedRecipient[]> {
+    const named = [
+      ...splitNames(input.to).map((name) => ({ name, bcc: false })),
+      ...splitNames(input.bcc ?? '').map((name) => ({ name, bcc: true })),
+    ]
+
+    if (named.length === 0)
+      throw new ValidationError(msg('error.messages.name-at-least-one-recipient'))
+
+    const seen = new Map<string, { name: string; bcc: boolean }>()
+    for (const entry of named) {
+      const key = entry.name.toLowerCase()
+      const existing = seen.get(key)
+      if (existing === undefined) seen.set(key, entry)
+      else if (!entry.bcc) seen.set(key, entry)
+    }
+
+    if (seen.size > MAX_RECIPIENTS) {
+      throw new ValidationError(
+        msg('error.messages.recipient-limit', { max: MAX_RECIPIENTS, count: seen.size }),
+      )
+    }
+
+    const resolved: ResolvedRecipient[] = []
+    for (const entry of seen.values()) {
+      const found = await this.policy.lookup(entry.name)
+      resolved.push({ name: entry.name, userId: found?.id ?? null, bcc: entry.bcc })
+    }
+
+    const unknown = resolved.filter((r) => r.userId === null).map((r) => r.name)
+    if (unknown.length > 0) {
+      throw new ValidationError(
+        msg('error.messages.unknown-recipients', {
+          count: unknown.length,
+          names: unknown.join(', '),
+        }),
+      )
+    }
+
+    if (resolved.some((r) => r.userId === input.authorUserId)) {
+      throw new ValidationError(msg('error.messages.send-message-yourself'))
+    }
+
+    return resolved
+  }
+
+  private async assertRoomFor(
+    authorUserId: number,
+    recipients: readonly ResolvedRecipient[],
+  ): Promise<void> {
+    const ids = [authorUserId, ...recipients.map((r) => r.userId as number)]
+    const [stored, limits] = await Promise.all([
+      this.repository.storedCounts(ids),
+      Promise.all(ids.map(async (id) => [id, await this.policy.limitsFor(id)] as const)),
+    ])
+
+    const limitById = new Map(limits)
+
+    const senderLimit = limitById.get(authorUserId)
+    if (senderLimit !== undefined && isFull(senderLimit.quota, stored.get(authorUserId) ?? 0)) {
+      throw new ForbiddenError(msg('error.messages.message-store-full-delete-some'))
+    }
+
+    const full: string[] = []
+    const closed: string[] = []
+    for (const recipient of recipients) {
+      const limit = limitById.get(recipient.userId as number)
+      if (limit === undefined) continue
+
+      const blocked =
+        this.policy.blocks === undefined
+          ? false
+          : await this.policy.blocks(recipient.userId as number, authorUserId)
+
+      if (!limit.canReceive || blocked) closed.push(recipient.name)
+      else if (isFull(limit.quota, stored.get(recipient.userId as number) ?? 0)) {
+        full.push(recipient.name)
+      }
+    }
+
+    if (closed.length > 0) {
+      throw new ForbiddenError(
+        msg('error.messages.recipients-closed', { names: closed.join(', ') }),
+      )
+    }
+    if (full.length > 0) {
+      throw new ForbiddenError(
+        msg('error.messages.recipients-full', { count: full.length, names: full.join(', ') }),
+      )
+    }
+  }
+
+  markRead(userId: number, copyIds: readonly number[]): Promise<number> {
+    return this.repository.setRead({ userId, copyIds, at: this.now() })
+  }
+
+  markUnread(userId: number, copyIds: readonly number[]): Promise<number> {
+    return this.repository.setRead({ userId, copyIds, at: null })
+  }
+
+  move(userId: number, copyIds: readonly number[], folder: MessageFolder): Promise<number> {
+    return this.repository.move({ userId, copyIds, folder })
+  }
+
+  remove(userId: number, copyIds: readonly number[]): Promise<number> {
+    return this.repository.remove({ userId, copyIds })
+  }
+
+  emptyTrash(userId: number): Promise<number> {
+    return this.repository.emptyFolder({ userId, folder: 'trash' })
+  }
+
+  async replyDraft(input: { messageId: number; userId: number }): Promise<Draft> {
+    const detail = await this.repository.detail(input)
+    if (detail === null) throw new NotFoundError(msg('error.messages.such-message'))
+
+    return {
+      to: detail.message.authorUsername,
+      subject: prefixed('Re: ', detail.message.subject),
+      message: quoted(detail.message),
+      replyToId: detail.message.id,
+    }
+  }
+
+  async forwardDraft(input: { messageId: number; userId: number }): Promise<Draft> {
+    const detail = await this.repository.detail(input)
+    if (detail === null) throw new NotFoundError(msg('error.messages.such-message'))
+
+    return {
+      to: '',
+      subject: prefixed('Fw: ', detail.message.subject),
+      message: quoted(detail.message),
+      replyToId: null,
+    }
+  }
+
+  forReport(messageId: number): Promise<PrivateMessage | null> {
+    return this.repository.forReport(messageId)
+  }
+
+  private async notify(run: () => Promise<void> | undefined): Promise<void> {
+    try {
+      await run()
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function isFull(quota: number, stored: number): boolean {
+  return quota > 0 && stored >= quota
+}
+
+export function splitNames(raw: string): readonly string[] {
+  return raw
+    .split(/[,;\n]/)
+    .map((name) => name.trim())
+    .filter((name) => name !== '')
+}
+
+function prefixed(prefix: string, subject: string): string {
+  const already = subject.slice(0, prefix.length).toLowerCase() === prefix.toLowerCase()
+  const next = already ? subject : `${prefix}${subject}`
+  return next.slice(0, SUBJECT_MAX)
+}
+
+function quoted(message: PrivateMessage): string {
+  return `${quoteBlock({
+    author: message.authorUsername,
+    markdown: sourceAsMarkdown(message.message, message.bodyFormat),
+  })}\n\n`
+}

package/src/types.ts

@@ -0,0 +1,150 @@
+export const MESSAGE_FOLDERS = ['inbox', 'sent', 'trash'] as const
+export type MessageFolder = (typeof MESSAGE_FOLDERS)[number]
+
+export const MESSAGE_ROLES = ['author', 'to', 'bcc'] as const
+export type MessageRole = (typeof MESSAGE_ROLES)[number]
+
+export function parseFolder(value: string): MessageFolder | null {
+  return MESSAGE_FOLDERS.includes(value as MessageFolder) ? (value as MessageFolder) : null
+}
+
+export const SUBJECT_MAX = 200
+export const BODY_MAX = 20_000
+export const MAX_RECIPIENTS = 10
+
+export interface PrivateMessage {
+  readonly id: number
+  readonly authorUserId: number | null
+  readonly authorUsername: string
+  readonly subject: string
+  readonly message: string
+  readonly messageHtml: string | null
+  readonly renderVersion: number
+  readonly bodyFormat: number
+  readonly vocabVersion: number
+  readonly replyToId: number | null
+  readonly receiptRequested: boolean
+  readonly sentAt: Date
+}
+
+export interface MessageCopy {
+  readonly id: number
+  readonly messageId: number
+  readonly ownerUserId: number
+  readonly folder: MessageFolder
+  readonly role: MessageRole
+  readonly readAt: Date | null
+}
+
+export interface MessageListRow {
+  readonly copyId: number
+  readonly messageId: number
+  readonly folder: MessageFolder
+  readonly role: MessageRole
+  readonly subject: string
+  readonly sentAt: Date
+  readonly readAt: Date | null
+  readonly counterparties: readonly string[]
+  readonly moreCounterparties: number
+}
+
+export interface MessageParticipant {
+  readonly userId: number
+  readonly username: string
+  readonly role: MessageRole
+  readonly readAt: Date | null
+}
+
+export interface MessageDetail {
+  readonly message: PrivateMessage
+  readonly copy: MessageCopy
+  readonly participants: readonly MessageParticipant[]
+}
+
+export interface FolderCounts {
+  readonly inbox: number
+  readonly sent: number
+  readonly trash: number
+  readonly unread: number
+  readonly stored: number
+}
+
+export interface ResolvedRecipient {
+  readonly name: string
+  readonly userId: number | null
+  readonly bcc: boolean
+}
+
+export interface MessagePolicy {
+  lookup(username: string): Promise<{ id: number; username: string } | null>
+  limitsFor(userId: number): Promise<{ quota: number; canReceive: boolean }>
+
+  blocks?(ownerUserId: number, senderUserId: number): Promise<boolean>
+}
+
+export interface MessageRepository {
+  list(input: {
+    readonly userId: number
+    readonly folder: MessageFolder
+    readonly limit: number
+    readonly before?: number | undefined
+    readonly offset?: number | undefined
+  }): Promise<readonly MessageListRow[]>
+
+  counts(userId: number): Promise<FolderCounts>
+
+  storedCounts(userIds: readonly number[]): Promise<ReadonlyMap<number, number>>
+
+  detail(input: {
+    readonly messageId: number
+    readonly userId: number
+  }): Promise<MessageDetail | null>
+
+  send(input: {
+    readonly authorUserId: number
+    readonly authorUsername: string
+    readonly subject: string
+    readonly message: string
+    readonly messageHtml: string
+    readonly renderVersion: number
+    readonly vocabVersion: number
+    readonly replyToId: number | null
+    readonly receiptRequested: boolean
+    readonly recipients: readonly { userId: number; bcc: boolean }[]
+    readonly at: Date
+  }): Promise<number>
+
+  setRead(input: {
+    readonly userId: number
+    readonly copyIds: readonly number[]
+    readonly at: Date | null
+  }): Promise<number>
+
+  move(input: {
+    readonly userId: number
+    readonly copyIds: readonly number[]
+    readonly folder: MessageFolder
+  }): Promise<number>
+
+  remove(input: { readonly userId: number; readonly copyIds: readonly number[] }): Promise<number>
+
+  emptyFolder(input: { readonly userId: number; readonly folder: MessageFolder }): Promise<number>
+
+  forReport(messageId: number): Promise<PrivateMessage | null>
+}
+
+export interface MessageNotifierPort {
+  messageReceived(input: {
+    readonly userId: number
+    readonly messageId: number
+    readonly fromUsername: string
+    readonly subject: string
+  }): Promise<void>
+
+  receiptRead(input: {
+    readonly userId: number
+    readonly messageId: number
+    readonly byUsername: string
+    readonly subject: string
+  }): Promise<void>
+}