@meith/notifications 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/notifications",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/notifications"
+  },
+  "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/i18n": "0.16.0",
+    "@meith/mail": "0.16.0"
+  }
+}

package/src/deliver-push.ts

@@ -0,0 +1,116 @@
+import { EN_CATALOG, sourceTranslator } from '@meith/i18n'
+
+import type { DeliveryOutcome, NotificationTranslatorResolver } from './deliver'
+import { PUSH_PAYLOAD_LIMIT, sendWebPush, type VapidDetails } from './push'
+import { renderNotification } from './render'
+import type { NotificationRepository } from './types'
+
+const BODY_LIMIT = 300
+
+export interface PushDeliveryResult {
+  readonly outcome: DeliveryOutcome
+  readonly sent: number
+  readonly pruned: number
+  readonly failed: number
+}
+
+export function pushPayload(input: {
+  readonly notificationId: number
+  readonly title: string
+  readonly body: string
+  readonly href: string | null
+  readonly badge: number
+}): string {
+  const payload = JSON.stringify({
+    id: input.notificationId,
+    title: input.title,
+    body: input.body.replace(/\s+/g, ' ').trim().slice(0, BODY_LIMIT),
+    href: input.href,
+    badge: input.badge,
+  })
+
+  return Buffer.byteLength(payload, 'utf8') > PUSH_PAYLOAD_LIMIT
+    ? JSON.stringify({
+        id: input.notificationId,
+        title: input.title.slice(0, BODY_LIMIT),
+        body: '',
+        href: input.href,
+        badge: input.badge,
+      })
+    : payload
+}
+
+export async function deliverNotificationPush(deps: {
+  readonly notifications: NotificationRepository
+  readonly vapid: VapidDetails
+  readonly notificationId: number
+  readonly translatorForLocale?: NotificationTranslatorResolver
+  readonly now?: () => Date
+  readonly send?: typeof sendWebPush
+}): Promise<PushDeliveryResult> {
+  const nothing = { sent: 0, pruned: 0, failed: 0 }
+
+  const deliverable = await deps.notifications.findForDelivery(deps.notificationId)
+  if (deliverable === null) return { outcome: 'missing', ...nothing }
+  if (deliverable.pushSentAt !== null) return { outcome: 'already-sent', ...nothing }
+  if (!deliverable.pushEnabled) return { outcome: 'declined', ...nothing }
+
+  const subscriptions = await deps.notifications.pushSubscriptionsFor(deliverable.recipient.userId)
+  if (subscriptions.length === 0) return { outcome: 'unsubscribed', ...nothing }
+
+  const t = await (deps.translatorForLocale ?? (() => sourceTranslator(EN_CATALOG)))(
+    deliverable.recipient.locale,
+  )
+  const view = renderNotification(deliverable.notification, t)
+  const now = deps.now ?? (() => new Date())
+  const send = deps.send ?? sendWebPush
+
+  const payload = pushPayload({
+    notificationId: view.id,
+    title: view.subject,
+    body: view.body,
+    href: view.href,
+    badge: await deps.notifications.unreadCount(deliverable.recipient.userId),
+  })
+
+  let sent = 0
+  let pruned = 0
+  let failed = 0
+
+  for (const subscription of subscriptions) {
+    const result = await send({
+      subscription: {
+        endpoint: subscription.endpoint,
+        p256dh: subscription.p256dh,
+        auth: subscription.auth,
+      },
+      payload,
+      vapid: deps.vapid,
+      now: now(),
+    })
+
+    if (result.outcome === 'sent') {
+      sent += 1
+      await deps.notifications.touchPushSubscription(subscription.id, now())
+      continue
+    }
+
+    if (result.outcome === 'gone') {
+      pruned += 1
+      await deps.notifications.prunePushSubscription(subscription.id)
+      continue
+    }
+
+    failed += 1
+  }
+
+  if (sent === 0 && failed > 0) {
+    throw new Error(
+      `Every push service refused notification ${deps.notificationId} (${failed} endpoint(s)).`,
+    )
+  }
+
+  await deps.notifications.markPushSent(deps.notificationId, now())
+
+  return { outcome: sent > 0 ? 'sent' : 'unsubscribed', sent, pruned, failed }
+}

package/src/deliver.ts

@@ -0,0 +1,48 @@
+import type { MailDriver } from '@meith/core'
+import { EN_CATALOG, sourceTranslator, type Translator } from '@meith/i18n'
+
+import { type MailBrand, renderNotificationMail } from './mail'
+import { renderNotification } from './render'
+import type { NotificationRepository } from './types'
+
+export type DeliveryOutcome = 'sent' | 'missing' | 'declined' | 'already-sent' | 'unsubscribed'
+
+export type NotificationTranslatorResolver = (locale: string) => Promise<Translator> | Translator
+
+export async function deliverNotificationEmail(deps: {
+  readonly notifications: NotificationRepository
+  readonly mail: MailDriver
+  readonly brand: MailBrand
+  readonly notificationId: number
+  readonly translatorForLocale?: NotificationTranslatorResolver
+  readonly now?: () => Date
+}): Promise<DeliveryOutcome> {
+  const deliverable = await deps.notifications.findForDelivery(deps.notificationId)
+  if (deliverable === null) return 'missing'
+  if (deliverable.emailSentAt !== null) return 'already-sent'
+  if (!deliverable.emailEnabled) return 'declined'
+
+  const t = await (deps.translatorForLocale ?? (() => sourceTranslator(EN_CATALOG)))(
+    deliverable.recipient.locale,
+  )
+  const mail = renderNotificationMail({
+    view: renderNotification(deliverable.notification, t),
+    brand: deps.brand,
+    recipientName: deliverable.recipient.username,
+    t,
+  })
+
+  const fromName = deps.brand.fromName ?? ''
+
+  await deps.mail.send({
+    to: deliverable.recipient.email,
+    subject: mail.subject,
+    text: mail.text,
+    html: mail.html,
+    ...(fromName === '' ? {} : { fromName }),
+  })
+
+  await deps.notifications.markEmailSent(deps.notificationId, (deps.now ?? (() => new Date()))())
+
+  return 'sent'
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+export {
+  type DeliveryOutcome,
+  deliverNotificationEmail,
+  type NotificationTranslatorResolver,
+} from './deliver'
+export {
+  deliverNotificationPush,
+  type PushDeliveryResult,
+  pushPayload,
+} from './deliver-push'
+export {
+  configurableKindsFor,
+  isNotificationKind,
+  NOTIFICATION_KINDS,
+  type NotificationAudience,
+  type NotificationKind,
+  type NotificationKindSpec,
+  notificationKind,
+  type RegisteredNotificationKind,
+} from './kinds'
+export {
+  type MailBrand,
+  type RenderedMail,
+  renderNotificationMail,
+} from './mail'
+export {
+  encryptPushPayload,
+  generateVapidKeys,
+  isVapidPrivateKey,
+  isVapidPublicKey,
+  PUSH_PAYLOAD_LIMIT,
+  PUSH_TTL_SECONDS,
+  type PushSendOutcome,
+  type PushSendResult,
+  type PushSubscriptionKeys,
+  pushAudience,
+  pushOutcomeFor,
+  sendWebPush,
+  type VapidDetails,
+  type VapidKeyPair,
+  vapidAuthorization,
+} from './push'
+export { type NotificationView, renderNotification } from './render'
+export {
+  MAX_STAFF_FANOUT,
+  NO_NOTIFICATION_AUDIT,
+  NOTIFICATIONS_PAGE_SIZE,
+  type NotificationAudit,
+  type NotificationPreferenceView,
+  NotificationService,
+} from './service'
+export type {
+  DeliverableNotification,
+  NotificationChannel,
+  NotificationChannelPreference,
+  NotificationData,
+  NotificationPage,
+  NotificationRecord,
+  NotificationRepository,
+  PushSubscriptionRecord,
+  RaiseInput,
+  RaiseResult,
+  SavePushSubscriptionInput,
+} from './types'

package/src/kinds.ts

@@ -0,0 +1,189 @@
+import type { NotificationChannel } from './types'
+
+export type NotificationAudience = 'member' | 'staff'
+
+interface NotificationKindBase {
+  readonly title: string
+  readonly description: string
+  readonly titleKey?: string
+  readonly descriptionKey?: string
+  readonly audience: NotificationAudience
+  readonly emailByDefault: boolean
+  readonly emailConfigurable: boolean
+  readonly pushByDefault: boolean
+  readonly pushConfigurable: boolean
+}
+
+export const NOTIFICATION_KINDS = [
+  {
+    id: 'warning.received',
+    titleKey: 'notification.warning.received.title',
+    descriptionKey: 'notification.warning.received.description',
+    title: 'You receive a warning',
+    description:
+      'A moderator has warned you. The notification records what it was for ' +
+      'and how many points it carried.',
+    audience: 'member',
+    emailByDefault: true,
+    emailConfigurable: true,
+    pushByDefault: true,
+    pushConfigurable: true,
+  },
+  {
+    id: 'report.actioned',
+    titleKey: 'notification.report.actioned.title',
+    descriptionKey: 'notification.report.actioned.description',
+    title: 'A report you filed is closed',
+    description:
+      'A moderator has resolved or rejected something you reported. The ' +
+      "moderator's private note is never included.",
+    audience: 'member',
+    emailByDefault: false,
+    emailConfigurable: true,
+    pushByDefault: false,
+    pushConfigurable: true,
+  },
+  {
+    id: 'subscription.reply',
+    titleKey: 'notification.subscription.reply.title',
+    descriptionKey: 'notification.subscription.reply.description',
+    title: 'A thread you follow gets a reply',
+    description:
+      'Somebody replies in a thread or forum you follow and asked to hear ' +
+      'about as it happens.',
+    audience: 'member',
+    emailByDefault: true,
+    emailConfigurable: true,
+    pushByDefault: true,
+    pushConfigurable: true,
+  },
+  {
+    id: 'subscription.digest',
+    titleKey: 'notification.subscription.digest.title',
+    descriptionKey: 'notification.subscription.digest.description',
+    title: 'Your daily or weekly digest is ready',
+    description:
+      'A summary of what arrived in the threads and forums you follow on a ' + 'digest cadence.',
+    audience: 'member',
+    emailByDefault: true,
+    emailConfigurable: true,
+    pushByDefault: false,
+    pushConfigurable: true,
+  },
+  {
+    id: 'post.mentioned',
+    titleKey: 'notification.post.mentioned.title',
+    descriptionKey: 'notification.post.mentioned.description',
+    title: 'Somebody mentions you in a post',
+    description:
+      'Somebody writes @your-name in a post. The notification links to the ' +
+      'post so you can read it in place.',
+    audience: 'member',
+    emailByDefault: true,
+    emailConfigurable: true,
+    pushByDefault: true,
+    pushConfigurable: true,
+  },
+  {
+    id: 'post.quoted',
+    titleKey: 'notification.post.quoted.title',
+    descriptionKey: 'notification.post.quoted.description',
+    title: 'Somebody quotes your post',
+    description:
+      'Somebody carries your words into their reply with the quote button. ' +
+      'The notification links to the reply that quotes you.',
+    audience: 'member',
+    emailByDefault: false,
+    emailConfigurable: true,
+    pushByDefault: false,
+    pushConfigurable: true,
+  },
+  {
+    id: 'pm.received',
+    titleKey: 'notification.pm.received.title',
+    descriptionKey: 'notification.pm.received.description',
+    title: 'You receive a private message',
+    description:
+      'Somebody sends you a private message. The notification carries who ' +
+      'from and the subject, never the message itself.',
+    audience: 'member',
+    emailByDefault: true,
+    emailConfigurable: true,
+    pushByDefault: true,
+    pushConfigurable: true,
+  },
+  {
+    id: 'pm.receipt',
+    titleKey: 'notification.pm.receipt.title',
+    descriptionKey: 'notification.pm.receipt.description',
+    title: 'A message you asked to track is read',
+    description:
+      'Somebody opens a private message you sent with a read receipt ' +
+      'requested. Raised once, on the first read.',
+    audience: 'member',
+    emailByDefault: false,
+    emailConfigurable: true,
+    pushByDefault: false,
+    pushConfigurable: true,
+  },
+  {
+    id: 'system.task_failed',
+    titleKey: 'notification.system.task_failed.title',
+    descriptionKey: 'notification.system.task_failed.description',
+    title: 'A scheduled task fails',
+    description:
+      'A background task raised an error. Counters, digests and search ' +
+      'indexing all run this way, so a task failing silently is how a board ' +
+      'drifts without anybody noticing.',
+    audience: 'staff',
+    emailByDefault: true,
+    emailConfigurable: true,
+    pushByDefault: false,
+    pushConfigurable: true,
+  },
+  {
+    id: 'marketplace.update_available',
+    titleKey: 'notification.marketplace.update_available.title',
+    descriptionKey: 'notification.marketplace.update_available.description',
+    title: 'An installed plugin has a newer listed version',
+    description:
+      'The daily catalog fetch finds a newer, compatible version of a plugin this ' +
+      'board runs. Sent once per version, whether or not anybody installs it.',
+    audience: 'staff',
+    emailByDefault: false,
+    emailConfigurable: true,
+    pushByDefault: false,
+    pushConfigurable: true,
+  },
+] as const satisfies readonly (NotificationKindBase & { readonly id: string })[]
+
+export type NotificationKind = (typeof NOTIFICATION_KINDS)[number]['id']
+
+export type NotificationKindSpec = NotificationKindBase & { readonly id: NotificationKind }
+
+export interface RegisteredNotificationKind extends NotificationKindBase {
+  readonly id: string
+}
+
+const BY_ID = new Map<string, NotificationKindSpec>(
+  NOTIFICATION_KINDS.map((kind) => [kind.id, kind as NotificationKindSpec]),
+)
+
+export function notificationKind(id: string): NotificationKindSpec | undefined {
+  return BY_ID.get(id)
+}
+
+export function isNotificationKind(id: string): id is NotificationKind {
+  return BY_ID.has(id)
+}
+
+export function configurableKindsFor(
+  audience: NotificationAudience,
+  channel: NotificationChannel = 'email',
+): readonly NotificationKindSpec[] {
+  return NOTIFICATION_KINDS.filter(
+    (kind) =>
+      kind.audience === audience &&
+      (channel === 'email' ? kind.emailConfigurable : kind.pushConfigurable),
+  ) as readonly NotificationKindSpec[]
+}

package/src/mail.ts

@@ -0,0 +1,73 @@
+import { EN_CATALOG, sourceTranslator, type Translator } from '@meith/i18n'
+import {
+  absoluteUrl,
+  type MailBody,
+  type MailBrand,
+  type MailFooterLine,
+  type RenderedMail,
+  renderMail,
+} from '@meith/mail'
+
+import type { NotificationView } from './render'
+
+export type { MailBrand, RenderedMail }
+
+const PREFERENCES_PATH = '/notifications/preferences'
+
+const UNSUBSCRIBE_PATH = '/unsubscribe'
+
+function footer(input: {
+  readonly boardName: string
+  readonly preferences: string | null
+  readonly unsubscribe: string | null
+  readonly t: Translator
+}): readonly MailFooterLine[] {
+  const { t } = input
+  const lines: MailFooterLine[] = [
+    { text: t.t('mail.footer.account', { board: input.boardName }) },
+    input.preferences === null
+      ? { text: t.t('mail.footer.preferencesNoLink') }
+      : { text: t.t('mail.footer.preferences'), href: input.preferences },
+  ]
+
+  if (input.unsubscribe !== null) {
+    lines.push({ text: t.t('mail.footer.unsubscribe'), href: input.unsubscribe })
+  }
+
+  return lines
+}
+
+export function renderNotificationMail(input: {
+  readonly view: NotificationView
+  readonly brand: MailBrand
+  readonly recipientName: string
+  readonly t?: Translator
+}): RenderedMail {
+  const { view, brand, recipientName } = input
+  const t = input.t ?? sourceTranslator(EN_CATALOG)
+
+  const boardName =
+    brand.boardName === '' ? t.t('notification.mail.boardFallback') : brand.boardName
+
+  const target = absoluteUrl(brand.boardUrl, view.href)
+  const preferences = absoluteUrl(brand.boardUrl, PREFERENCES_PATH)
+  const unsubscribe =
+    view.unsubscribeToken === null
+      ? null
+      : absoluteUrl(
+          brand.boardUrl,
+          `${UNSUBSCRIBE_PATH}?token=${encodeURIComponent(view.unsubscribeToken)}`,
+        )
+
+  const body: MailBody = {
+    title: view.subject,
+    greeting: t.t('notification.mail.greeting', { username: recipientName }),
+    paragraphs: view.body === '' ? [] : view.body.split(/\n{2,}/),
+    ...(target === null
+      ? {}
+      : { action: { label: t.t('mail.notification.action', { board: boardName }), href: target } }),
+    footer: footer({ boardName, preferences, unsubscribe, t }),
+  }
+
+  return renderMail({ brand: { ...brand, boardName }, body, t })
+}