@strav/notification 1.0.0-alpha.28 → 1.0.0-alpha.29

package/README.md

@@ -1,6 +1,6 @@
 # @strav/notification
 
-Multi-channel notifications for Strav 1.0. One fluent surface (`notifications.send(notifiable, notification)`) that fan-outs to ≥1 channel drivers — mail / database / log / webhook / broadcast today; Discord / SMS channels in follow-up slices.
+Multi-channel notifications for Strav 1.0. One fluent surface (`notifications.send(notifiable, notification)`) that fan-outs to ≥1 channel drivers — mail / database / log / webhook / broadcast / discord / sse today; SMS channel in a follow-up slice.
 
 ```ts
 import { BaseNotification, type Notifiable, NotificationManager } from '@strav/notification'
@@ -32,5 +32,7 @@ Canonical docs live in [`docs/notification/README.md`](../../docs/notification/R
 | Log | `@strav/notification/log` | Routes through `@strav/kernel`'s `Logger`. Useful for dev + tests. |
 | Webhook | `@strav/notification/webhook` | POSTs a signed JSON envelope (`x-strav-signature: sha256=...` over `${timestamp}.${body}`) to a configured endpoint. Exports `verifyWebhookSignature` for receiver-side validation. |
 | Broadcast | `@strav/notification/broadcast` | Publishes a `BroadcastEvent` via `@strav/broadcast`'s `Broadcaster`. Pairs with `router.sse(...)` so live UI clients receive the same dispatch. |
+| Discord | `@strav/notification/discord` | POSTs `notification.toDiscord(notifiable)` to a Discord webhook URL. Returns a string (shorthand for `{ content }`) or a `DiscordMessage` with `embeds` / `components` / per-message `webhookUrl` override. Per-recipient URLs via `notifiable.discordWebhookUrl`. |
+| SSE | `@strav/notification/sse` | In-process pub/sub. Reads `notification.toSSE(notifiable)` and pushes to every active subscriber for that notifiable. HTTP handlers consume subscriptions via `driver.subscribe(id, { notifiableType? })` + `sseResponse()` from `@strav/http`. |
 
-Deferred: Discord, SMS channel drivers. Apps register custom channels via `manager.extend(name, factory)`.
+Deferred: SMS channel driver. Apps register custom channels via `manager.extend(name, factory)`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@strav/notification",
-  "version": "1.0.0-alpha.28",
-  "description": "Strav multi-channel notifications — NotificationManager fan-out across channel drivers (mail / database / log / webhook / broadcast). Manager+drivers shape; new channels register via `manager.extend(name, factory)`. Discord / SMS channels ship in follow-up slices.",
+  "version": "1.0.0-alpha.29",
+  "description": "Strav multi-channel notifications — NotificationManager fan-out across channel drivers (mail / database / log / webhook / broadcast / discord / sse). Manager+drivers shape; new channels register via `manager.extend(name, factory)`.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -12,6 +12,8 @@
     "./log": "./src/drivers/log/index.ts",
     "./webhook": "./src/drivers/webhook/index.ts",
     "./broadcast": "./src/drivers/broadcast/index.ts",
+    "./discord": "./src/drivers/discord/index.ts",
+    "./sse": "./src/drivers/sse/index.ts",
     "./tenanted": "./src/drivers/database/tenanted/index.ts"
   },
   "files": [
@@ -25,12 +27,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.28"
+    "@strav/kernel": "1.0.0-alpha.29"
+  },
+  "devDependencies": {
+    "@strav/broadcast": "1.0.0-alpha.29",
+    "@strav/database": "1.0.0-alpha.29",
+    "@strav/http": "1.0.0-alpha.29",
+    "@strav/mail": "1.0.0-alpha.29"
   },
   "peerDependencies": {
-    "@strav/broadcast": "1.0.0-alpha.28",
-    "@strav/database": "1.0.0-alpha.28",
-    "@strav/mail": "1.0.0-alpha.28",
+    "@strav/broadcast": "1.0.0-alpha.29",
+    "@strav/database": "1.0.0-alpha.29",
+    "@strav/http": "1.0.0-alpha.29",
+    "@strav/mail": "1.0.0-alpha.29",
     "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {
@@ -40,9 +49,11 @@
     "@strav/database": {
       "optional": true
     },
+    "@strav/http": {
+      "optional": true
+    },
     "@strav/mail": {
       "optional": true
     }
-  },
-  "devDependencies": null
+  }
 }

package/src/drivers/discord/discord_config.ts

@@ -0,0 +1,51 @@
+/**
+ * Vendor-specific config shape for the Discord channel. The
+ * discriminator `driver: 'discord'` selects this factory at
+ * `manager.use(...)` time.
+ *
+ * The Discord channel ships as a *webhook* driver — apps configure
+ * one Discord webhook URL per channel and POST against it. Per-
+ * recipient routing happens two ways:
+ *
+ *   1. Notifiables expose their own `discordWebhookUrl` field, and the
+ *      driver uses it instead of the channel default.
+ *   2. The notification's `toDiscord(notifiable)` hook returns a
+ *      `{ webhookUrl, ... }` envelope that overrides both.
+ *
+ * Bot tokens / interaction-aware messaging is out of scope for this
+ * slice — apps that need it bring their own integration and dispatch
+ * through `manager.extend(name, factory)`.
+ */
+
+import type { ChannelConfig } from '../../notification_config.ts'
+
+export interface DiscordChannelConfig extends ChannelConfig {
+  driver: 'discord'
+  /**
+   * Default webhook URL. Optional — apps that route every dispatch
+   * via per-recipient or per-notification URLs omit it. The driver
+   * fails the dispatch (returns `delivered: false`, no error) when
+   * neither the notification, the notifiable, nor the config supplies
+   * a URL — same opt-out semantics as the mail / webhook channels.
+   */
+  webhookUrl?: string
+  /**
+   * Default username shown for messages sent via this channel. Apps
+   * commonly set this to their product name. Per-message overrides
+   * win — `toDiscord` can return `{ username: '...' }`.
+   */
+  username?: string
+  /**
+   * Default avatar URL. Same override rules as `username`.
+   */
+  avatarUrl?: string
+  /**
+   * When `true`, the driver appends `?wait=true` to the webhook URL.
+   * Discord then responds 200 with the created message JSON instead
+   * of 204 with an empty body — useful if downstream wants the
+   * message ID via the dispatch result's `reference`. Default `false`.
+   */
+  wait?: boolean
+  /** Request timeout in ms. Default `5000`. */
+  timeoutMs?: number
+}

package/src/drivers/discord/discord_notification_driver.ts

@@ -0,0 +1,246 @@
+/**
+ * `DiscordNotificationDriver` — POSTs notifications to a Discord
+ * webhook URL.
+ *
+ * The wire shape matches Discord's
+ * [Execute Webhook](https://discord.com/developers/docs/resources/webhook#execute-webhook)
+ * endpoint:
+ *
+ *   POST {webhookUrl}[?wait=true]
+ *   content-type: application/json
+ *
+ *   {
+ *     "content":  "Hi from Strav",            // ≤ 2000 chars
+ *     "username": "Strav",                    // overrides webhook default
+ *     "avatar_url": "https://...",
+ *     "embeds":   [ { "title": "...", ... } ],
+ *     "components": [ ... ],
+ *     "allowed_mentions": { "parse": [] }
+ *   }
+ *
+ * Reads `notification.toDiscord(notifiable)` for the body. The hook
+ * can return either:
+ *
+ *   - A string — shorthand for `{ content: <string> }`.
+ *   - A `DiscordMessage` — full envelope, including an optional
+ *     `webhookUrl` field that overrides the channel default.
+ *
+ * Webhook URL resolution order: hook return → `notifiable.discordWebhookUrl`
+ * → `config.webhookUrl`. When none resolve, the dispatch is skipped
+ * (`{ delivered: false }` with no error) — same intentional opt-out
+ * the mail + webhook channels use.
+ *
+ * Wire normalisation:
+ *   - `username` / `avatar_url`: per-message > channel default. The
+ *     hook sees the channel default as a `defaults` argument so it
+ *     can branch on it if needed.
+ *   - Camel-case keys on the JS side (`avatarUrl`, `allowedMentions`,
+ *     `threadName`) are translated to Discord's snake_case wire form
+ *     before send. This keeps apps' notification code idiomatic.
+ *
+ * On 2xx the driver returns `{ delivered: true }`. With `wait: true`,
+ * Discord echoes the created message JSON — the driver returns its
+ * `id` as the dispatch `reference`. On 4xx / 5xx / network failure
+ * the driver throws `NotificationDeliveryError`; 429 + 5xx flag
+ * `retryable: true`.
+ */
+
+import type { Notifiable } from '../../notifiable.ts'
+import type { BaseNotification } from '../../notification.ts'
+import type { NotificationDriver } from '../../notification_driver.ts'
+import { NotificationDeliveryError } from '../../notification_error.ts'
+import type { NotificationContext, NotificationDeliveryResult } from '../../types.ts'
+
+/** Shape returned by `notification.toDiscord(notifiable)`. */
+export interface DiscordMessage {
+  /** Message text body. Up to 2000 chars (Discord limit — not enforced here). */
+  content?: string
+  /** Override the webhook's configured display name for this message. */
+  username?: string
+  /** Override the webhook's avatar for this message. */
+  avatarUrl?: string
+  /** Embeds — up to 10. Apps build them per the Discord embed object spec. */
+  embeds?: ReadonlyArray<Record<string, unknown>>
+  /** Message-component arrays (buttons, selects). */
+  components?: ReadonlyArray<Record<string, unknown>>
+  /**
+   * Allowed-mentions control. Default behaviour at Discord is to
+   * resolve every mention in `content` — set
+   * `{ parse: [] }` to suppress all `@mentions`.
+   */
+  allowedMentions?: Record<string, unknown>
+  /** Render the message as text-to-speech. */
+  tts?: boolean
+  /** When the webhook targets a forum, name the new thread. */
+  threadName?: string
+  /** Message flags bitfield (e.g. SUPPRESS_EMBEDS = 1 << 2). */
+  flags?: number
+  /**
+   * Override the webhook URL for this dispatch only. Useful when the
+   * notification carries its own routing decision; takes priority
+   * over `notifiable.discordWebhookUrl` and `config.webhookUrl`.
+   */
+  webhookUrl?: string
+  /**
+   * Pass-through escape hatch — keys placed here are added to the
+   * Discord payload verbatim (snake_case expected). Use for fields
+   * the typed envelope hasn't grown to cover yet.
+   */
+  extra?: Record<string, unknown>
+}
+
+/** Hook surface — apps add `toDiscord(notifiable, defaults)` on their notification. */
+interface DiscordCapableNotification extends BaseNotification {
+  toDiscord?(
+    notifiable: Notifiable,
+    defaults: { username?: string; avatarUrl?: string },
+  ): string | DiscordMessage | Promise<string | DiscordMessage>
+}
+
+interface NotifiableWithDiscordWebhook extends Notifiable {
+  discordWebhookUrl?: string
+}
+
+export interface DiscordNotificationDriverOptions {
+  name: string
+  webhookUrl?: string
+  username?: string
+  avatarUrl?: string
+  wait?: boolean
+  timeoutMs?: number
+  /** Custom `fetch` for tests. */
+  fetch?: typeof fetch
+}
+
+export class DiscordNotificationDriver implements NotificationDriver {
+  readonly name: string
+  private readonly defaultWebhookUrl: string | undefined
+  private readonly username: string | undefined
+  private readonly avatarUrl: string | undefined
+  private readonly wait: boolean
+  private readonly timeoutMs: number
+  private readonly fetchFn: typeof fetch
+
+  constructor(options: DiscordNotificationDriverOptions) {
+    this.name = options.name
+    this.defaultWebhookUrl = options.webhookUrl
+    this.username = options.username
+    this.avatarUrl = options.avatarUrl
+    this.wait = options.wait ?? false
+    this.timeoutMs = options.timeoutMs ?? 5000
+    this.fetchFn = options.fetch ?? fetch
+  }
+
+  async send(
+    notifiable: Notifiable,
+    notification: BaseNotification,
+    context: NotificationContext,
+  ): Promise<NotificationDeliveryResult> {
+    const hook = (notification as DiscordCapableNotification).toDiscord
+    if (typeof hook !== 'function') {
+      return { channel: this.name, delivered: false }
+    }
+
+    const defaults = {
+      ...(this.username !== undefined ? { username: this.username } : {}),
+      ...(this.avatarUrl !== undefined ? { avatarUrl: this.avatarUrl } : {}),
+    }
+    const raw = await hook.call(notification, notifiable, defaults)
+    const message: DiscordMessage = typeof raw === 'string' ? { content: raw } : raw
+
+    const webhookUrl =
+      message.webhookUrl ??
+      (notifiable as NotifiableWithDiscordWebhook).discordWebhookUrl ??
+      this.defaultWebhookUrl
+    if (webhookUrl === undefined || webhookUrl === '') {
+      return { channel: this.name, delivered: false }
+    }
+
+    const body = JSON.stringify(serialise(message, defaults))
+    const endpoint = this.wait ? appendWait(webhookUrl) : webhookUrl
+
+    let response: Response
+    try {
+      response = await this.fetchFn(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      })
+    } catch (cause) {
+      throw new NotificationDeliveryError(
+        `DiscordNotificationDriver: network failure for channel "${this.name}".`,
+        {
+          context: {
+            channel: this.name,
+            notifiableId: notifiable.id,
+            notification: notification.constructor.name,
+            retryable: true,
+          },
+          cause,
+        },
+      )
+    }
+
+    if (response.ok) {
+      // When `wait: true`, Discord returns 200 with the created message
+      // JSON; we expose its id as the dispatch reference. Without
+      // `wait`, Discord returns 204 — no reference available, fall
+      // back to the notification context id for correlation.
+      let reference: string = context.id
+      if (this.wait && response.status === 200) {
+        try {
+          const created = (await response.json()) as { id?: string }
+          if (typeof created.id === 'string') reference = created.id
+        } catch {
+          // Discord drifted — keep the context id as the reference.
+        }
+      }
+      return { channel: this.name, delivered: true, reference }
+    }
+
+    const responseBody = await response.text().catch(() => '')
+    throw new NotificationDeliveryError(
+      `DiscordNotificationDriver: Discord responded HTTP ${response.status} ${response.statusText}.`,
+      {
+        context: {
+          channel: this.name,
+          notifiableId: notifiable.id,
+          notification: notification.constructor.name,
+          status: response.status,
+          retryable: response.status >= 500 || response.status === 429,
+          responseBody: responseBody.slice(0, 1024),
+        },
+      },
+    )
+  }
+}
+
+/**
+ * Map our camel-case `DiscordMessage` shape onto Discord's wire JSON.
+ * Per-message values win over channel defaults; `extra` is spread
+ * verbatim so apps can reach fields the typed envelope hasn't grown
+ * to yet (e.g. `poll`, `applied_tags` for forum posts).
+ */
+function serialise(
+  m: DiscordMessage,
+  defaults: { username?: string; avatarUrl?: string },
+): Record<string, unknown> {
+  const wire: Record<string, unknown> = { ...m.extra }
+  if (m.content !== undefined) wire.content = m.content
+  const username = m.username ?? defaults.username
+  if (username !== undefined) wire.username = username
+  const avatar = m.avatarUrl ?? defaults.avatarUrl
+  if (avatar !== undefined) wire.avatar_url = avatar
+  if (m.embeds !== undefined) wire.embeds = m.embeds
+  if (m.components !== undefined) wire.components = m.components
+  if (m.allowedMentions !== undefined) wire.allowed_mentions = m.allowedMentions
+  if (m.tts !== undefined) wire.tts = m.tts
+  if (m.threadName !== undefined) wire.thread_name = m.threadName
+  if (m.flags !== undefined) wire.flags = m.flags
+  return wire
+}
+
+function appendWait(url: string): string {
+  return url.includes('?') ? `${url}&wait=true` : `${url}?wait=true`
+}

package/src/drivers/discord/discord_notification_provider.ts

@@ -0,0 +1,37 @@
+/**
+ * ServiceProvider that registers the discord-channel factory on the
+ * `NotificationManager`. Apps include this in their provider list
+ * AFTER `NotificationProvider`; the factory resolves whenever
+ * `config.notification.channels.<name>.driver === 'discord'`.
+ *
+ * Unlike the webhook channel, the Discord factory does NOT validate
+ * `webhookUrl` upfront — apps can intentionally omit it and route
+ * every dispatch via per-recipient (`notifiable.discordWebhookUrl`)
+ * or per-message (`toDiscord` returning `{ webhookUrl }`) URLs. The
+ * driver fails the dispatch (`delivered: false`) when none resolve.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { NotificationManager } from '../../notification_manager.ts'
+import type { DiscordChannelConfig } from './discord_config.ts'
+import { DiscordNotificationDriver } from './discord_notification_driver.ts'
+
+export class DiscordNotificationProvider extends ServiceProvider {
+  override readonly name = 'notification.discord'
+  override readonly dependencies = ['notification']
+
+  override async boot(app: Application): Promise<void> {
+    const manager = app.resolve(NotificationManager)
+    manager.extend('discord', ({ instanceName, config }) => {
+      const cfg = config as DiscordChannelConfig
+      return new DiscordNotificationDriver({
+        name: instanceName,
+        ...(cfg.webhookUrl !== undefined ? { webhookUrl: cfg.webhookUrl } : {}),
+        ...(cfg.username !== undefined ? { username: cfg.username } : {}),
+        ...(cfg.avatarUrl !== undefined ? { avatarUrl: cfg.avatarUrl } : {}),
+        ...(cfg.wait !== undefined ? { wait: cfg.wait } : {}),
+        ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
+      })
+    })
+  }
+}

package/src/drivers/discord/index.ts

@@ -0,0 +1,7 @@
+export type { DiscordChannelConfig } from './discord_config.ts'
+export {
+  type DiscordMessage,
+  DiscordNotificationDriver,
+  type DiscordNotificationDriverOptions,
+} from './discord_notification_driver.ts'
+export { DiscordNotificationProvider } from './discord_notification_provider.ts'

package/src/drivers/sse/index.ts

@@ -0,0 +1,7 @@
+export type { SSEChannelConfig } from './sse_config.ts'
+export {
+  SSENotificationDriver,
+  type SSENotificationDriverOptions,
+  type SSESubscribeOptions,
+} from './sse_notification_driver.ts'
+export { SSENotificationProvider } from './sse_notification_provider.ts'

package/src/drivers/sse/sse_config.ts

@@ -0,0 +1,28 @@
+/**
+ * Vendor-specific config shape for the SSE channel. The
+ * discriminator `driver: 'sse'` selects this factory at
+ * `manager.use(...)` time.
+ *
+ * Unlike the broadcast channel, the SSE channel is a *pure in-process*
+ * pub/sub registry — no `Broadcaster` peer, no Postgres LISTEN/NOTIFY.
+ * One process, one registry; subscribers live on the same Bun instance
+ * that dispatches the notification. Apps that need cross-process
+ * fan-out wire the broadcast channel instead.
+ *
+ * When neither is appropriate (single-process apps that don't want a
+ * pub/sub backplane at all), this is the simplest way to push a live
+ * notification into a `router.sse(...)` handler.
+ */
+
+import type { ChannelConfig } from '../../notification_config.ts'
+
+export interface SSEChannelConfig extends ChannelConfig {
+  driver: 'sse'
+  /**
+   * Per-subscriber queue size. When a subscriber falls behind by
+   * more than `queueSize` events, the oldest events are dropped
+   * (best-effort delivery — the SSE contract anyway; clients
+   * recover via `Last-Event-ID` on reconnect). Default `64`.
+   */
+  queueSize?: number
+}

package/src/drivers/sse/sse_notification_driver.ts

@@ -0,0 +1,234 @@
+/**
+ * `SSENotificationDriver` — in-process pub/sub channel for live
+ * notifications.
+ *
+ * The driver maintains a `Map<key, Set<Subscriber>>` keyed by the
+ * notifiable's identity. `send(notifiable, ...)` reads
+ * `notification.toSSE(notifiable)` for the event body and pushes it
+ * to every subscriber for that notifiable; HTTP handlers consume
+ * subscriptions via `subscribe(id, { notifiableType? })` and pipe the
+ * iterable into `sseResponse(...)` from `@strav/http`.
+ *
+ *   const route = router.get('/notifications/stream', async (ctx) => {
+ *     const user = ctx.auth.user!
+ *     const driver = notifications.use('sse') as SSENotificationDriver
+ *     const stream = driver.subscribe(user.id, { notifiableType: 'User' })
+ *     return sseResponse(stream, { signal: ctx.request.raw.signal })
+ *   })
+ *
+ * Why this exists alongside the broadcast channel:
+ *
+ *   - **Broadcast** (`./broadcast`) routes through `@strav/broadcast`'s
+ *     `Broadcaster` — pluggable backplane (memory / postgres), supports
+ *     multi-process fan-out via LISTEN/NOTIFY.
+ *   - **SSE** (this driver) is a single-process registry with no
+ *     peer dependency. Right answer for the common "I just want my
+ *     user to see the notification in their open tab" case without
+ *     pulling in a broadcast driver.
+ *
+ * Backpressure — each subscriber holds a bounded queue (default 64).
+ * When a slow consumer falls behind, the oldest events are dropped
+ * to make room (and `droppedEvents` increments). Lost events are
+ * the SSE contract anyway: clients recover by reading
+ * `Last-Event-ID` on reconnect and asking the app to backfill from
+ * the database channel.
+ *
+ * Skips delivery (`{ delivered: false }`, no error) when the hook is
+ * absent OR no subscribers exist for the notifiable. Apps inspect
+ * `result.delivered === false && result.error === undefined` to
+ * branch on "user is offline" vs a real failure.
+ */
+
+import type { SSEEvent } from '@strav/http'
+import type { Notifiable } from '../../notifiable.ts'
+import type { BaseNotification } from '../../notification.ts'
+import type { NotificationDriver } from '../../notification_driver.ts'
+import { NotificationDeliveryError } from '../../notification_error.ts'
+import type { NotificationContext, NotificationDeliveryResult } from '../../types.ts'
+
+/** Hook surface — apps add `toSSE(notifiable)` on their notification. */
+interface SSECapableNotification extends BaseNotification {
+  toSSE?(notifiable: Notifiable): SSEEvent | string | Promise<SSEEvent | string>
+}
+
+export interface SSESubscribeOptions {
+  /**
+   * Constrain the subscription to a specific notifiable type. When
+   * both subscriber and dispatch provide a `notifiableType`, they
+   * must match for the event to land. When either omits it, the id
+   * alone is used (looser routing — useful for tests).
+   */
+  notifiableType?: string
+}
+
+export interface SSENotificationDriverOptions {
+  name: string
+  /** Per-subscriber bounded queue size. Default 64. */
+  queueSize?: number
+}
+
+interface Subscriber {
+  push(event: SSEEvent): void
+  close(): void
+  droppedEvents: number
+}
+
+export class SSENotificationDriver implements NotificationDriver {
+  readonly name: string
+  private readonly queueSize: number
+  private readonly subscribers = new Map<string, Set<Subscriber>>()
+
+  constructor(options: SSENotificationDriverOptions) {
+    this.name = options.name
+    this.queueSize = options.queueSize ?? 64
+  }
+
+  /**
+   * Open a subscription for `id` (+ optional `notifiableType`). The
+   * returned iterable yields one `SSEEvent` per matched dispatch and
+   * runs cleanly when the consumer breaks out of the `for await`
+   * loop or the iterator's `return()` is called (which
+   * `sseResponse()` does on client disconnect).
+   */
+  subscribe(id: string | number, options: SSESubscribeOptions = {}): AsyncIterable<SSEEvent> {
+    const key = subscriberKey(id, options.notifiableType)
+    return makeSubscription(this.subscribers, key, this.queueSize)
+  }
+
+  /**
+   * How many active subscribers exist for `(id, notifiableType?)`.
+   * Useful for the database channel pairing — apps may want to skip
+   * persisting a "live" event when the user already has an SSE tab
+   * open and consumed it.
+   */
+  subscriberCount(id: string | number, options: SSESubscribeOptions = {}): number {
+    const key = subscriberKey(id, options.notifiableType)
+    return this.subscribers.get(key)?.size ?? 0
+  }
+
+  async send(
+    notifiable: Notifiable,
+    notification: BaseNotification,
+    context: NotificationContext,
+  ): Promise<NotificationDeliveryResult> {
+    const hook = (notification as SSECapableNotification).toSSE
+    if (typeof hook !== 'function') {
+      return { channel: this.name, delivered: false }
+    }
+
+    const key = subscriberKey(notifiable.id, notifiable.notifiableType)
+    const targets = this.subscribers.get(key)
+    if (targets === undefined || targets.size === 0) {
+      return { channel: this.name, delivered: false }
+    }
+
+    let raw: SSEEvent | string
+    try {
+      raw = await hook.call(notification, notifiable)
+    } catch (cause) {
+      throw new NotificationDeliveryError(
+        `SSENotificationDriver: toSSE() threw for channel "${this.name}".`,
+        {
+          context: {
+            channel: this.name,
+            notifiableId: notifiable.id,
+            notification: notification.constructor.name,
+          },
+          cause,
+        },
+      )
+    }
+
+    // Default `event` to the notification class and `id` to the
+    // dispatch context id — both can be overridden by the hook.
+    const base: SSEEvent = typeof raw === 'string' ? { data: raw } : { ...raw }
+    if (base.id === undefined) base.id = context.id
+    if (base.event === undefined) base.event = notification.constructor.name
+
+    // Snapshot the subscriber set before iterating — handlers may
+    // close + remove themselves mid-broadcast (e.g. heartbeat detects
+    // a dead connection).
+    for (const sub of Array.from(targets)) sub.push(base)
+
+    return { channel: this.name, delivered: true, reference: context.id }
+  }
+}
+
+function subscriberKey(id: string | number, notifiableType: string | undefined): string {
+  return `${notifiableType ?? ''}|${id}`
+}
+
+/**
+ * One subscriber = one bounded queue + a wake/sleep gate. The
+ * generator's `finally` block deregisters the subscriber from the
+ * shared map — so closing the response (or breaking the loop) tears
+ * down the slot cleanly.
+ */
+function makeSubscription(
+  registry: Map<string, Set<Subscriber>>,
+  key: string,
+  capacity: number,
+): AsyncIterable<SSEEvent> {
+  return {
+    [Symbol.asyncIterator]() {
+      const queue: SSEEvent[] = []
+      let closed = false
+      let waker: (() => void) | undefined
+      const subscriber: Subscriber = {
+        droppedEvents: 0,
+        push(event) {
+          if (closed) return
+          if (queue.length >= capacity) {
+            queue.shift()
+            subscriber.droppedEvents += 1
+          }
+          queue.push(event)
+          waker?.()
+        },
+        close() {
+          if (closed) return
+          closed = true
+          waker?.()
+        },
+      }
+
+      let bucket = registry.get(key)
+      if (bucket === undefined) {
+        bucket = new Set()
+        registry.set(key, bucket)
+      }
+      bucket.add(subscriber)
+
+      const detach = (): void => {
+        subscriber.close()
+        const set = registry.get(key)
+        if (set !== undefined) {
+          set.delete(subscriber)
+          if (set.size === 0) registry.delete(key)
+        }
+      }
+
+      return {
+        async next(): Promise<IteratorResult<SSEEvent>> {
+          while (true) {
+            const event = queue.shift()
+            if (event !== undefined) return { value: event, done: false }
+            if (closed) return { value: undefined, done: true }
+            await new Promise<void>((resolve) => {
+              waker = resolve
+            })
+            waker = undefined
+          }
+        },
+        async return(): Promise<IteratorResult<SSEEvent>> {
+          detach()
+          return { value: undefined, done: true }
+        },
+        async throw(err): Promise<IteratorResult<SSEEvent>> {
+          detach()
+          throw err
+        },
+      }
+    },
+  }
+}

package/src/drivers/sse/sse_notification_provider.ts

@@ -0,0 +1,29 @@
+/**
+ * ServiceProvider that registers the SSE-channel factory on the
+ * `NotificationManager`. Apps include this in their provider list
+ * AFTER `NotificationProvider`; the factory resolves whenever
+ * `config.notification.channels.<name>.driver === 'sse'`.
+ *
+ * No peer dependencies — the driver is pure in-process.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { NotificationManager } from '../../notification_manager.ts'
+import type { SSEChannelConfig } from './sse_config.ts'
+import { SSENotificationDriver } from './sse_notification_driver.ts'
+
+export class SSENotificationProvider extends ServiceProvider {
+  override readonly name = 'notification.sse'
+  override readonly dependencies = ['notification']
+
+  override async boot(app: Application): Promise<void> {
+    const manager = app.resolve(NotificationManager)
+    manager.extend('sse', ({ instanceName, config }) => {
+      const cfg = config as SSEChannelConfig
+      return new SSENotificationDriver({
+        name: instanceName,
+        ...(cfg.queueSize !== undefined ? { queueSize: cfg.queueSize } : {}),
+      })
+    })
+  }
+}

package/src/index.ts

@@ -1,9 +1,9 @@
 // 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.
+// BaseNotification abstract class + Notifiable interface + channel
+// drivers under subpaths (./mail, ./database, ./log, ./webhook,
+// ./broadcast, ./discord, ./sse). SMS channel follows in a later slice.
 
 export {
   MockNotificationDriver,