@meith/moderation 0.16.0

package/src/modcp.ts

@@ -0,0 +1,174 @@
+import { ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+export const MODCP_PAGE_SIZE = 25
+
+export interface ModLogEntry {
+  readonly id: number
+  readonly action: string
+  readonly actorUserId: number | null
+  readonly actorUsername: string | null
+  readonly forumId: number | null
+  readonly forumTitle: string | null
+  readonly detail: readonly { readonly label: string; readonly value: string }[]
+  readonly at: Date
+}
+
+export interface ModLogPage {
+  readonly entries: readonly ModLogEntry[]
+  readonly nextCursor?: string
+}
+
+export interface ModeratedForum {
+  readonly forumId: number
+  readonly title: string
+  readonly slug: string
+  readonly pending: number
+  readonly openReports: number
+  readonly rights: readonly string[]
+}
+
+export interface IpMatch {
+  readonly userId: number
+  readonly username: string
+  readonly matchedOn: 'registration' | 'last_visit' | 'both'
+  readonly lastActiveAt: Date | null
+}
+
+export interface ModCpRepository {
+  log(input: {
+    readonly forumIds: readonly number[]
+    readonly actorUserId: number
+    readonly limit: number
+    readonly after?: string | undefined
+  }): Promise<ModLogPage>
+
+  workload(
+    forumIds: readonly number[],
+  ): Promise<ReadonlyMap<number, { pending: number; openReports: number }>>
+
+  ipMatches(userId: number, limit: number): Promise<readonly IpMatch[]>
+
+  ipPrefixesFor(userId: number): Promise<{ registration: string | null; lastVisit: string | null }>
+
+  recordIpLookup(input: {
+    readonly actorUserId: number
+    readonly subjectUserId: number
+    readonly matches: number
+    readonly at: Date
+  }): Promise<void>
+}
+
+export interface ModeratorPanelRights {
+  readonly access: boolean
+  readonly ipLookup: boolean
+}
+
+export class ModeratorPanel {
+  private readonly repo: ModCpRepository
+  private readonly now: () => Date
+
+  constructor(deps: { modcp: ModCpRepository; now?: () => Date }) {
+    this.repo = deps.modcp
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async log(input: {
+    readonly forumIds: readonly number[]
+    readonly actorUserId: number
+    readonly after?: string | undefined
+  }): Promise<ModLogPage> {
+    return this.repo.log({
+      forumIds: input.forumIds,
+      actorUserId: input.actorUserId,
+      limit: MODCP_PAGE_SIZE,
+      ...(input.after === undefined ? {} : { after: input.after }),
+    })
+  }
+
+  async dashboard(input: {
+    readonly forums: readonly {
+      forumId: number
+      title: string
+      slug: string
+      rights: readonly string[]
+    }[]
+  }): Promise<readonly ModeratedForum[]> {
+    if (input.forums.length === 0) return []
+
+    const workload = await this.repo.workload(input.forums.map((f) => f.forumId))
+    return input.forums
+      .map((forum) => ({
+        ...forum,
+        pending: workload.get(forum.forumId)?.pending ?? 0,
+        openReports: workload.get(forum.forumId)?.openReports ?? 0,
+      }))
+      .sort(
+        (a, b) =>
+          b.pending + b.openReports - (a.pending + a.openReports) || a.title.localeCompare(b.title),
+      )
+  }
+
+  async lookUpIp(input: {
+    readonly subjectUserId: number
+    readonly actorUserId: number
+    readonly rights: ModeratorPanelRights
+    readonly limit?: number
+  }): Promise<{
+    readonly prefixes: { registration: string | null; lastVisit: string | null }
+    readonly matches: readonly IpMatch[]
+  }> {
+    if (!input.rights.access || !input.rights.ipLookup) {
+      throw new ValidationError(msg('error.moderation.look-up-addresses'))
+    }
+
+    const prefixes = await this.repo.ipPrefixesFor(input.subjectUserId)
+    const matches = await this.repo.ipMatches(input.subjectUserId, input.limit ?? MODCP_PAGE_SIZE)
+
+    await this.repo.recordIpLookup({
+      actorUserId: input.actorUserId,
+      subjectUserId: input.subjectUserId,
+      matches: matches.length,
+      at: this.now(),
+    })
+
+    return { prefixes, matches }
+  }
+}
+
+export const MOD_LOG_LABEL_KEYS: Readonly<Record<string, string>> = {
+  'moderation.approve': 'board.modlog.moderation.approve',
+  'moderation.reject': 'board.modlog.moderation.reject',
+  'thread.lock': 'board.modlog.thread.lock',
+  'thread.unlock': 'board.modlog.thread.unlock',
+  'thread.stick': 'board.modlog.thread.stick',
+  'thread.unstick': 'board.modlog.thread.unstick',
+  'thread.move': 'board.modlog.thread.move',
+  'thread.delete': 'board.modlog.thread.delete',
+  'thread.restore': 'board.modlog.thread.restore',
+  'thread.split': 'board.modlog.thread.split',
+  'thread.merge': 'board.modlog.thread.merge',
+  'thread.copy': 'board.modlog.thread.copy',
+  'inline.approve': 'board.modlog.inline.approve',
+  'inline.delete': 'board.modlog.inline.delete',
+  'inline.restore': 'board.modlog.inline.restore',
+  'inline.lock': 'board.modlog.inline.lock',
+  'inline.unlock': 'board.modlog.inline.unlock',
+  'inline.stick': 'board.modlog.inline.stick',
+  'inline.unstick': 'board.modlog.inline.unstick',
+  'inline.move': 'board.modlog.inline.move',
+  'post.edit': 'board.modlog.post.edit',
+  'post.delete': 'board.modlog.post.delete',
+  'post.restore': 'board.modlog.post.restore',
+  'report.resolve': 'board.modlog.report.resolve',
+  'report.reject': 'board.modlog.report.reject',
+  'warning.issue': 'board.modlog.warning.issue',
+  'warning.revoke': 'board.modlog.warning.revoke',
+  'signature.lock': 'board.modlog.signature.lock',
+  'signature.unlock': 'board.modlog.signature.unlock',
+  'avatar.lock': 'board.modlog.avatar.lock',
+  'avatar.unlock': 'board.modlog.avatar.unlock',
+  'modcp.ip_lookup': 'board.modlog.ipLookup',
+}
+
+export const MOD_LOG_ACTIONS: readonly string[] = Object.keys(MOD_LOG_LABEL_KEYS)

package/src/queue.ts

@@ -0,0 +1,149 @@
+import { ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+export type QueueItemKind = 'thread' | 'post'
+
+export interface QueueSelection {
+  readonly kind: QueueItemKind
+  readonly id: number
+}
+
+export interface QueueItem extends QueueSelection {
+  readonly forumId: number
+  readonly forumTitle: string
+  readonly threadId: number
+  readonly threadSlug: string
+  readonly threadTitle: string
+  readonly authorUserId: number | null
+  readonly authorUsername: string
+  readonly excerpt: string
+  readonly createdAt: Date
+}
+
+export interface QueuePage {
+  readonly items: readonly QueueItem[]
+  readonly nextCursor?: string
+}
+
+export interface PendingItem extends QueueSelection {
+  readonly forumId: number
+}
+
+export type QueueDecision = 'approve' | 'reject'
+
+export interface QueueOutcome {
+  readonly decision: QueueDecision
+  readonly applied: number
+  readonly refused: number
+  readonly missing: number
+  /** The items the decision was carried out on, for whoever has to announce it. */
+  readonly decided: readonly { readonly kind: QueueItemKind; readonly id: number }[]
+}
+
+export interface ModerationQueueRepository {
+  list(
+    forumIds: readonly number[],
+    options: {
+      readonly limit: number
+      readonly after?: string
+      readonly offset?: number
+    },
+  ): Promise<QueuePage>
+
+  countPending(forumIds: readonly number[]): Promise<number>
+
+  resolve(selection: readonly QueueSelection[]): Promise<readonly PendingItem[]>
+
+  apply(input: {
+    readonly decision: QueueDecision
+    readonly threadIds: readonly number[]
+    readonly postIds: readonly number[]
+    readonly actorUserId: number
+    readonly at: Date
+  }): Promise<number>
+}
+
+export const MAX_CHUNK = 200
+
+export const QUEUE_PAGE_SIZE = 25
+
+export class ModerationQueue {
+  private readonly queue: ModerationQueueRepository
+  private readonly now: () => Date
+
+  constructor(deps: { queue: ModerationQueueRepository; now?: () => Date }) {
+    this.queue = deps.queue
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async list(
+    moderatedForumIds: readonly number[],
+    options: { readonly after?: string; readonly offset?: number } = {},
+  ): Promise<QueuePage> {
+    if (moderatedForumIds.length === 0) return { items: [] }
+    return this.queue.list(moderatedForumIds, {
+      limit: QUEUE_PAGE_SIZE,
+      ...(options.after === undefined ? {} : { after: options.after }),
+      ...(options.offset === undefined ? {} : { offset: options.offset }),
+    })
+  }
+
+  async countPending(moderatedForumIds: readonly number[]): Promise<number> {
+    if (moderatedForumIds.length === 0) return 0
+    return this.queue.countPending(moderatedForumIds)
+  }
+
+  async decide(input: {
+    readonly selection: readonly QueueSelection[]
+    readonly decision: QueueDecision
+    readonly moderatedForumIds: ReadonlySet<number>
+    readonly actorUserId: number
+  }): Promise<QueueOutcome> {
+    if (input.selection.length === 0) {
+      throw new ValidationError(msg('error.moderation.select-at-least-one-item'))
+    }
+    if (input.selection.length > MAX_CHUNK) {
+      throw new ValidationError(msg('error.moderation.queue-chunk', { max: MAX_CHUNK }))
+    }
+
+    const unique = new Map<string, QueueSelection>()
+    for (const item of input.selection) unique.set(`${item.kind}:${item.id}`, item)
+
+    const pending = await this.queue.resolve([...unique.values()])
+    const missing = unique.size - pending.length
+
+    const allowed = pending.filter((item) => input.moderatedForumIds.has(item.forumId))
+    const refused = pending.length - allowed.length
+
+    const applied =
+      allowed.length === 0
+        ? 0
+        : await this.queue.apply({
+            decision: input.decision,
+            threadIds: allowed.filter((i) => i.kind === 'thread').map((i) => i.id),
+            postIds: allowed.filter((i) => i.kind === 'post').map((i) => i.id),
+            actorUserId: input.actorUserId,
+            at: this.now(),
+          })
+
+    return {
+      decision: input.decision,
+      applied,
+      refused,
+      missing,
+      decided: applied === 0 ? [] : allowed.map((item) => ({ kind: item.kind, id: item.id })),
+    }
+  }
+}
+
+export function parseSelection(values: readonly string[]): QueueSelection[] {
+  const out: QueueSelection[] = []
+  for (const value of values) {
+    const match = /^(thread|post):([1-9]\d*)$/.exec(value)
+    if (!match) continue
+    const id = Number(match[2])
+    if (!Number.isSafeInteger(id)) continue
+    out.push({ kind: match[1] as QueueItemKind, id })
+  }
+  return out
+}

package/src/reports.ts

@@ -0,0 +1,260 @@
+import { ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+export const REPORT_TARGET_KINDS = ['post', 'thread', 'user', 'private_message'] as const
+export type ReportTargetKind = (typeof REPORT_TARGET_KINDS)[number]
+
+export type ReportStatus = 'open' | 'resolved' | 'rejected'
+
+export const REASON_MIN = 3
+export const REASON_MAX = 1000
+
+export interface ReportTarget {
+  readonly kind: ReportTargetKind
+  readonly id: number
+  readonly forumId: number | null
+  readonly threadId: number | null
+  readonly threadAuthorUserId: number | null
+  readonly label: string
+}
+
+export interface NewReport {
+  readonly target: ReportTarget
+  readonly reporterUserId: number
+  readonly reason: string
+  readonly at: Date
+}
+
+export interface ReportRow {
+  readonly id: number
+  readonly kind: ReportTargetKind
+  readonly targetId: number
+  readonly forumId: number | null
+  readonly threadId: number | null
+  readonly targetLabel: string
+  readonly reporterUserId: number | null
+  readonly reporterUsername: string | null
+  readonly reason: string
+  readonly status: ReportStatus
+  readonly assignedToUserId: number | null
+  readonly assignedToUsername: string | null
+  readonly createdAt: Date
+}
+
+export interface ReportEvent {
+  readonly id: number
+  readonly kind: 'opened' | 'assigned' | 'unassigned' | 'resolved' | 'rejected' | 'note'
+  readonly actorUserId: number | null
+  readonly actorUsername: string | null
+  readonly note: string | null
+  readonly createdAt: Date
+}
+
+export interface ReportPage {
+  readonly rows: readonly ReportRow[]
+  readonly nextCursor?: string
+}
+
+export interface ReportScope {
+  readonly forumIds: readonly number[]
+  readonly global: boolean
+}
+
+export interface ReportRepository {
+  resolveTarget(
+    kind: ReportTargetKind,
+    id: number,
+    reporterUserId: number,
+  ): Promise<ReportTarget | null>
+
+  open(report: NewReport): Promise<number | null>
+
+  listOpen(
+    scope: ReportScope,
+    options: {
+      readonly limit: number
+      readonly after?: string
+      readonly offset?: number
+    },
+  ): Promise<ReportPage>
+
+  countOpen(scope: ReportScope): Promise<number>
+
+  find(id: number): Promise<{ report: ReportRow; events: readonly ReportEvent[] } | null>
+
+  assign(input: {
+    readonly reportId: number
+    readonly toUserId: number | null
+    readonly actorUserId: number
+    readonly at: Date
+  }): Promise<boolean>
+
+  close(input: {
+    readonly reportId: number
+    readonly status: 'resolved' | 'rejected'
+    readonly note: string | null
+    readonly actorUserId: number
+    readonly at: Date
+  }): Promise<boolean>
+}
+
+export const REPORTS_PAGE_SIZE = 25
+
+export interface ReportNotifierPort {
+  reportClosed(input: {
+    readonly reporterUserId: number
+    readonly reportId: number
+    readonly outcome: 'resolved' | 'rejected'
+    readonly targetLabel: string
+  }): Promise<void>
+}
+
+export class ReportService {
+  private readonly reports: ReportRepository
+  private readonly notifier: ReportNotifierPort | null
+  private readonly now: () => Date
+
+  constructor(deps: {
+    reports: ReportRepository
+    notifier?: ReportNotifierPort | null
+    now?: () => Date
+  }) {
+    this.reports = deps.reports
+    this.notifier = deps.notifier ?? null
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async file(input: {
+    readonly kind: ReportTargetKind
+    readonly targetId: number
+    readonly reason: string
+    readonly reporterUserId: number
+  }): Promise<{ reportId: number; duplicate: boolean }> {
+    const reason = input.reason.trim()
+    if (reason.length < REASON_MIN) {
+      throw new ValidationError(msg('error.moderation.say-what-wrong-with-briefly'))
+    }
+    if (reason.length > REASON_MAX) {
+      throw new ValidationError(msg('error.moderation.reason-length', { max: REASON_MAX }))
+    }
+
+    const target = await this.reports.resolveTarget(
+      input.kind,
+      input.targetId,
+      input.reporterUserId,
+    )
+    if (target === null) throw new ValidationError(msg('error.moderation.exist'))
+
+    const reportId = await this.reports.open({
+      target,
+      reporterUserId: input.reporterUserId,
+      reason,
+      at: this.now(),
+    })
+
+    return reportId === null ? { reportId: 0, duplicate: true } : { reportId, duplicate: false }
+  }
+
+  async listOpen(
+    scope: ReportScope,
+    options: { readonly after?: string; readonly offset?: number } = {},
+  ): Promise<ReportPage> {
+    if (scope.forumIds.length === 0 && !scope.global) return { rows: [] }
+    return this.reports.listOpen(scope, {
+      limit: REPORTS_PAGE_SIZE,
+      ...(options.after === undefined ? {} : { after: options.after }),
+      ...(options.offset === undefined ? {} : { offset: options.offset }),
+    })
+  }
+
+  async countOpen(scope: ReportScope): Promise<number> {
+    if (scope.forumIds.length === 0 && !scope.global) return 0
+    return this.reports.countOpen(scope)
+  }
+
+  async open(
+    reportId: number,
+    scope: ReportScope,
+  ): Promise<{ report: ReportRow; events: readonly ReportEvent[] } | null> {
+    const found = await this.reports.find(reportId)
+    if (found === null) return null
+    return inScope(found.report, scope) ? found : null
+  }
+
+  async assign(input: {
+    readonly reportId: number
+    readonly toUserId: number | null
+    readonly actorUserId: number
+    readonly scope: ReportScope
+  }): Promise<void> {
+    await this.requireInScope(input.reportId, input.scope)
+    const changed = await this.reports.assign({
+      reportId: input.reportId,
+      toUserId: input.toUserId,
+      actorUserId: input.actorUserId,
+      at: this.now(),
+    })
+    if (!changed) throw new ValidationError(msg('error.moderation.report-already-closed'))
+  }
+
+  async close(input: {
+    readonly reportId: number
+    readonly status: 'resolved' | 'rejected'
+    readonly note: string
+    readonly actorUserId: number
+    readonly scope: ReportScope
+  }): Promise<void> {
+    const note = input.note.trim()
+    if (note.length > REASON_MAX) {
+      throw new ValidationError(msg('error.moderation.note-length', { max: REASON_MAX }))
+    }
+
+    const report = await this.requireInScope(input.reportId, input.scope)
+    const changed = await this.reports.close({
+      reportId: input.reportId,
+      status: input.status,
+      note: note.length === 0 ? null : note,
+      actorUserId: input.actorUserId,
+      at: this.now(),
+    })
+    if (!changed) throw new ValidationError(msg('error.moderation.report-already-closed'))
+
+    await this.notifyReporter(report, input.status, input.actorUserId)
+  }
+
+  private async notifyReporter(
+    report: ReportRow,
+    outcome: 'resolved' | 'rejected',
+    actorUserId: number,
+  ): Promise<void> {
+    if (this.notifier === null) return
+    if (report.reporterUserId === null || report.reporterUserId === actorUserId) return
+
+    await this.notifier
+      .reportClosed({
+        reporterUserId: report.reporterUserId,
+        reportId: report.id,
+        outcome,
+        targetLabel: report.targetLabel,
+      })
+      .catch(() => undefined)
+  }
+
+  private async requireInScope(reportId: number, scope: ReportScope): Promise<ReportRow> {
+    const found = await this.reports.find(reportId)
+    if (found === null || !inScope(found.report, scope)) {
+      throw new ValidationError(msg('error.moderation.report-exist'))
+    }
+    return found.report
+  }
+}
+
+export function inScope(report: ReportRow, scope: ReportScope): boolean {
+  return report.forumId === null ? scope.global : scope.forumIds.includes(report.forumId)
+}
+
+export function parseTargetKind(value: string | undefined): ReportTargetKind | null {
+  return REPORT_TARGET_KINDS.includes(value as ReportTargetKind)
+    ? (value as ReportTargetKind)
+    : null
+}