@strav/notification 1.0.0-alpha.25

package/src/index.ts

@@ -0,0 +1,38 @@
+// Public API of @strav/notification.
+//
+// V1: NotificationManager facade + NotificationDriver interface +
+// BaseNotification abstract class + Notifiable interface + four
+// channel drivers under subpaths (./mail, ./database, ./log, ./webhook).
+// Broadcast / SSE / Discord / SMS channels deferred to future slices.
+
+export {
+  MockNotificationDriver,
+  type MockNotificationRecord,
+  mockNotificationDriverFactory,
+} from './drivers/mock.ts'
+export type { Notifiable } from './notifiable.ts'
+export { BaseNotification } from './notification.ts'
+export type {
+  ChannelConfig,
+  NotificationConfig,
+} from './notification_config.ts'
+export type {
+  NotificationDriver,
+  NotificationDriverFactory,
+} from './notification_driver.ts'
+export {
+  NotificationConfigError,
+  NotificationDeliveryError,
+  NotificationError,
+  UnknownChannelError,
+} from './notification_error.ts'
+export {
+  NotificationManager,
+  type NotificationManagerOptions,
+} from './notification_manager.ts'
+export { NotificationProvider } from './notification_provider.ts'
+export type {
+  NotificationContext,
+  NotificationDeliveryResult,
+  NotificationDispatchResult,
+} from './types.ts'

package/src/notifiable.ts

@@ -0,0 +1,22 @@
+/**
+ * `Notifiable` — the minimum a notification recipient must expose.
+ *
+ * Apps' domain models implement this interface (or extend it via mixin
+ * / Repository pattern). Channel-specific data lives on the domain
+ * shape: a `User` notifiable might have `email: string` for the mail
+ * channel, `phone: string` for an SMS channel, and any per-channel
+ * routing-preference fields the app cares about.
+ *
+ * The framework stays out of the routing decision — each notification's
+ * `via(notifiable)` returns the channels to dispatch through, and each
+ * channel reads what it needs off the notifiable directly.
+ */
+
+export interface Notifiable {
+  /** Identity. Channels persist this on delivery rows so apps can resolve back. */
+  readonly id: string | number
+  /** Class / type name. Channels record this alongside the id for polymorphic resolution. */
+  readonly notifiableType?: string
+  /** Apps add channel-specific fields directly: `email`, `phone`, `preferences`, …. */
+  [key: string]: unknown
+}

package/src/notification.ts

@@ -0,0 +1,26 @@
+/**
+ * `BaseNotification` — apps subclass this to define a notification.
+ *
+ * Two responsibilities the subclass owns:
+ *
+ *   1. `via(notifiable)` — return the channel names the manager
+ *      fan-outs to. Apps that pre-load a user's channel preferences
+ *      branch here (e.g. `notifiable.preferences.email === true`).
+ *
+ *   2. One `to<Channel>(notifiable)` hook per channel the notification
+ *      supports. The hook returns the channel's input shape (a `Message`
+ *      for mail, a `NotificationPayload` for database, etc.). Channels
+ *      whose hook isn't implemented get skipped — no runtime error.
+ *
+ * Hooks aren't declared on the base class because each channel knows
+ * its own input type and reaches for the named method at dispatch time.
+ * Apps that want compile-time hook enforcement extend a per-channel
+ * mixin (out of scope for v1 — bring your own discipline for now).
+ */
+
+import type { Notifiable } from './notifiable.ts'
+
+export abstract class BaseNotification {
+  /** Channel names the manager fan-outs to. Apps override. */
+  abstract via(notifiable: Notifiable): readonly string[]
+}

package/src/notification_config.ts

@@ -0,0 +1,26 @@
+/**
+ * Notification configuration shape — what `config.notification` looks
+ * like. Mirrors the manager-pattern config used by `@strav/payment`
+ * and `@strav/social`: a `default` channel key + a `channels` map
+ * keyed by name. Each channel entry carries its driver + driver-
+ * specific options.
+ *
+ * `default` is OPTIONAL on this manager: notifications route per-call
+ * via `via(notifiable)`, not via a single configured default. Apps
+ * set `default` only when they want `manager.use()` (no arg) to
+ * resolve to a specific channel.
+ */
+
+export interface NotificationConfig {
+  /** Optional default channel name — must exist in `channels` when set. */
+  default?: string
+  /** Channel registry. Each entry is one configured backend. */
+  channels: Record<string, ChannelConfig>
+}
+
+export interface ChannelConfig {
+  /** Driver identifier — matches a registered factory (`mail`, `database`, `log`, or custom). */
+  driver: string
+  /** Free-form driver-specific fields. */
+  [key: string]: unknown
+}

package/src/notification_driver.ts

@@ -0,0 +1,40 @@
+/**
+ * `NotificationDriver` — the contract every channel implements.
+ *
+ * One driver instance per configured channel. The manager calls
+ * `send(notifiable, notification, context)` once per channel that
+ * `notification.via(notifiable)` named; drivers either deliver or
+ * return `{ delivered: false, error }`.
+ *
+ * Drivers MAY ignore notifications they can't service (no
+ * `to<Channel>` hook, recipient missing channel-required fields) by
+ * returning `{ delivered: false }` with no `error` — the manager
+ * surfaces this in the dispatch result without treating it as a
+ * failure.
+ */
+
+import type { Notifiable } from './notifiable.ts'
+import type { BaseNotification } from './notification.ts'
+import type { NotificationContext, NotificationDeliveryResult } from './types.ts'
+
+export interface NotificationDriver {
+  /** Identifier — matches `config.notification.channels` key. */
+  readonly name: string
+
+  send(
+    notifiable: Notifiable,
+    notification: BaseNotification,
+    context: NotificationContext,
+  ): Promise<NotificationDeliveryResult>
+}
+
+/**
+ * Channel factory — apps register custom channels via
+ * `manager.extend(name, factory)`. The factory receives the channel's
+ * config sub-tree plus an `instanceName` (the key under
+ * `config.notification.channels`).
+ */
+export type NotificationDriverFactory = (args: {
+  instanceName: string
+  config: { driver: string; [key: string]: unknown }
+}) => NotificationDriver

package/src/notification_error.ts

@@ -0,0 +1,62 @@
+/**
+ * Typed error hierarchy. Mirrors `@strav/payment`'s `PaymentError`
+ * shape: a base `NotificationError` extending `StravError`, plus
+ * subclasses with specific codes apps can branch on.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class NotificationError extends StravError {
+  constructor(
+    message: string,
+    options: {
+      code?: string
+      status?: number
+      context?: Record<string, unknown>
+      cause?: unknown
+    } = {},
+  ) {
+    super(
+      message,
+      { code: options.code ?? 'notification.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class NotificationConfigError extends NotificationError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'notification.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class UnknownChannelError extends NotificationError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'notification.unknown_channel',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class NotificationDeliveryError extends NotificationError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'notification.delivery',
+      status: 502,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}

package/src/notification_manager.ts

@@ -0,0 +1,135 @@
+/**
+ * `NotificationManager` — the facade apps inject for sending
+ * notifications.
+ *
+ * Two concept clusters:
+ *
+ *   - **Channels.** Apps declare configured channels in
+ *     `config.notification.channels`. The manager constructs each
+ *     channel driver lazily on first `use(name)` + memoizes. Custom
+ *     channels register via `manager.extend(name, factory)`. Tests
+ *     hand-wire via `manager.useDriver(name, driver)`.
+ *
+ *   - **Fan-out.** `send(notifiable, notification)` calls
+ *     `notification.via(notifiable)` to get the channel list, then
+ *     dispatches each channel in order, collecting per-channel
+ *     `NotificationDeliveryResult`s into a single
+ *     `NotificationDispatchResult`. Channels that throw are
+ *     captured into the result (`delivered: false`, `error: ...`)
+ *     — the manager never rethrows; apps inspect the result.
+ *
+ * One ULID per send shared across channels (for correlation in
+ * downstream logs / persistence). The manager constructs the
+ * `NotificationContext` once and threads it through.
+ */
+
+import { ulid } from '@strav/kernel'
+import type { Notifiable } from './notifiable.ts'
+import type { BaseNotification } from './notification.ts'
+import type { NotificationConfig } from './notification_config.ts'
+import type { NotificationDriver, NotificationDriverFactory } from './notification_driver.ts'
+import { NotificationConfigError, UnknownChannelError } from './notification_error.ts'
+import type {
+  NotificationContext,
+  NotificationDeliveryResult,
+  NotificationDispatchResult,
+} from './types.ts'
+
+export interface NotificationManagerOptions {
+  config: NotificationConfig
+}
+
+export class NotificationManager {
+  readonly config: NotificationConfig
+
+  private readonly drivers = new Map<string, NotificationDriver>()
+  private readonly extensions = new Map<string, NotificationDriverFactory>()
+
+  constructor(options: NotificationManagerOptions) {
+    const { config } = options
+    if (config.default !== undefined && !config.channels[config.default]) {
+      throw new NotificationConfigError(
+        `NotificationManager: default channel "${config.default}" is not configured.`,
+        {
+          context: {
+            default: config.default,
+            available: Object.keys(config.channels),
+          },
+        },
+      )
+    }
+    this.config = config
+  }
+
+  // ─── Channel routing ──────────────────────────────────────────────────
+
+  /** Resolve a channel by name (or the default when omitted). */
+  use(name?: string): NotificationDriver {
+    const key = name ?? this.config.default
+    if (key === undefined) {
+      throw new NotificationConfigError(
+        'NotificationManager.use(): no name given and no default channel is configured.',
+      )
+    }
+    const cached = this.drivers.get(key)
+    if (cached) return cached
+
+    const cfg = this.config.channels[key]
+    if (!cfg) {
+      throw new UnknownChannelError(`NotificationManager: channel "${key}" is not configured.`, {
+        context: { requested: key, available: Object.keys(this.config.channels) },
+      })
+    }
+
+    const factory = this.extensions.get(cfg.driver)
+    if (!factory) {
+      throw new UnknownChannelError(
+        `NotificationManager: unknown driver "${cfg.driver}" for channel "${key}". Register it via \`manager.extend("${cfg.driver}", factory)\`.`,
+        { context: { driver: cfg.driver, available: [...this.extensions.keys()] } },
+      )
+    }
+    const driver = factory({ instanceName: key, config: cfg })
+    this.drivers.set(key, driver)
+    return driver
+  }
+
+  /** Register a channel driver factory. Adapter packages call this from their ServiceProvider. */
+  extend(driverName: string, factory: NotificationDriverFactory): void {
+    this.extensions.set(driverName, factory)
+  }
+
+  /** Hand-wire a channel instance under an app-chosen name (tests / one-offs). */
+  useDriver(instanceName: string, driver: NotificationDriver): void {
+    this.drivers.set(instanceName, driver)
+  }
+
+  // ─── Fan-out ──────────────────────────────────────────────────────────
+
+  async send(
+    notifiable: Notifiable,
+    notification: BaseNotification,
+  ): Promise<NotificationDispatchResult> {
+    const context: NotificationContext = {
+      id: ulid(),
+      dispatchedAt: new Date(),
+    }
+    const channels = notification.via(notifiable)
+    const deliveries: NotificationDeliveryResult[] = []
+
+    for (const channelName of channels) {
+      try {
+        const driver = this.use(channelName)
+        const result = await driver.send(notifiable, notification, context)
+        deliveries.push(result)
+      } catch (err) {
+        deliveries.push({
+          channel: channelName,
+          delivered: false,
+          error: err instanceof Error ? err : new Error(String(err)),
+        })
+      }
+    }
+
+    return { id: context.id, deliveries }
+  }
+}

package/src/notification_provider.ts

@@ -0,0 +1,42 @@
+/**
+ * `NotificationProvider` — ServiceProvider that wires
+ * `NotificationManager` into the container.
+ *
+ * Eager construction at boot — a malformed config (missing default
+ * channel, unknown channel driver) surfaces at startup, not on first
+ * `send()` call.
+ *
+ * Channel adapter packages register themselves AFTER this provider:
+ * each `<Channel>NotificationProvider` declares `dependencies =
+ * ['notification']` and calls `manager.extend(name, factory)` from
+ * its `boot()` so the channel becomes available without the manager
+ * needing to import it.
+ */
+
+import { type Application, ConfigError, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import type { NotificationConfig } from './notification_config.ts'
+import { NotificationManager } from './notification_manager.ts'
+
+export class NotificationProvider extends ServiceProvider {
+  override readonly name = 'notification'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(NotificationManager, (c) => {
+      const config = c.resolve(ConfigRepository).get('notification') as
+        | NotificationConfig
+        | undefined
+      if (!config) {
+        throw new ConfigError(
+          'NotificationProvider: `config.notification` is missing. Add `config/notification.ts` with at least one channel.',
+        )
+      }
+      return new NotificationManager({ config })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    // Force-resolve so config errors surface at boot, not on first call.
+    app.resolve(NotificationManager)
+  }
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-send metadata. The manager constructs one on every `send()` call
+ * and threads it through each channel driver. Apps can use the
+ * `idempotencyKey` to deduplicate downstream (e.g. preventing the
+ * database channel from inserting two rows for the same retry).
+ */
+export interface NotificationContext {
+  /** ULID — stable per send, shared across channels. */
+  id: string
+  dispatchedAt: Date
+  /** App-supplied idempotency key. Optional. */
+  idempotencyKey?: string
+}
+
+/**
+ * Outcome a channel driver reports back. The manager aggregates these
+ * into a `NotificationDispatchResult` so apps can branch on per-channel
+ * success / failure without each driver having to throw.
+ */
+export interface NotificationDeliveryResult {
+  channel: string
+  delivered: boolean
+  /** Driver-specific reference (mail message id, database row id, etc.). */
+  reference?: string
+  /** Set when `delivered === false`. */
+  error?: Error
+}
+
+export interface NotificationDispatchResult {
+  /** Notification ULID — matches `NotificationContext.id`. */
+  id: string
+  /** One entry per channel attempted, in the order `via()` returned them. */
+  deliveries: readonly NotificationDeliveryResult[]
+}