198 lines
6.2 KiB
Markdown
198 lines
6.2 KiB
Markdown
# OpenSpec Change: enterprise-notification-channel
|
|
|
|
- **Change ID**: enterprise-notification-channel
|
|
- **Package**: `@suaveplan/notification-channel`
|
|
- **Category**: universal
|
|
- **Target path**: `universal/messaging/notification-channel`
|
|
- **Status**: IN PROGRESS
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/notification-channel.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/notification-channel` on the genesis branch from scratch at enterprise quality. The package provides multi-channel notification routing: a `NotificationChannel` interface, concrete channel adapters (email, SMS, push/in-app, Slack webhook, Discord webhook, Telegram), a `NotificationRouter` that dispatches a notification through registered channels based on priority rules, template rendering per channel via `@suaveplan/email-templates` or `@suaveplan/templates`, preference-aware routing (per-recipient opt-in/opt-out per channel), delivery tracking integration, and a `NotificationService` orchestrator. The main-branch version sat at 95.61% coverage. Genesis adds structured errors, Zod schemas, OTel instrumentation, retry, and property-based tests.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
The package does not exist on genesis yet — this is a fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `NotificationError`; `NOTIF.*` error codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `EventBusLike` |
|
|
| `@suaveplan/events` (`workspace:^`) | Notification lifecycle events |
|
|
| `@suaveplan/templates` (`workspace:^`) | Channel-specific template rendering |
|
|
| `@suaveplan/email-templates` (`workspace:^`) | Email-specific template rendering |
|
|
| `@suaveplan/retry` (`workspace:^`) | Retry on channel send failures |
|
|
| `@suaveplan/suppression` (`workspace:^`) | Email/SMS suppression list check |
|
|
| `zod` (`catalog:forms`) | Schema validation |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
|
|
|
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
### Core types
|
|
|
|
```ts
|
|
type ChannelType = 'email' | 'sms' | 'push' | 'in-app' | 'slack' | 'discord' | 'telegram'
|
|
|
|
interface Notification {
|
|
id: string
|
|
recipient: NotificationRecipient
|
|
templateName: string
|
|
channels: ChannelType[]
|
|
context: Record<string, unknown>
|
|
priority: 'low' | 'normal' | 'high' | 'critical'
|
|
metadata: Record<string, unknown>
|
|
}
|
|
|
|
interface NotificationRecipient {
|
|
id: string
|
|
email?: string
|
|
phone?: string
|
|
pushToken?: string
|
|
slackUserId?: string
|
|
discordUserId?: string
|
|
telegramChatId?: string | number
|
|
preferences?: ChannelPreferences
|
|
}
|
|
|
|
type ChannelPreferences = Partial<Record<ChannelType, boolean>>
|
|
|
|
interface NotificationResult {
|
|
notificationId: string
|
|
channel: ChannelType
|
|
status: 'sent' | 'failed' | 'suppressed' | 'skipped'
|
|
error?: string
|
|
}
|
|
```
|
|
|
|
### `NotificationChannel` interface
|
|
|
|
```ts
|
|
interface NotificationChannel {
|
|
readonly type: ChannelType
|
|
send(recipient: NotificationRecipient, subject: string, body: string, options?: ChannelSendOptions): Promise<void>
|
|
isAvailableFor(recipient: NotificationRecipient): boolean
|
|
}
|
|
```
|
|
|
|
### `NotificationService`
|
|
|
|
```ts
|
|
class NotificationService {
|
|
constructor(options: NotificationServiceOptions)
|
|
register(channel: NotificationChannel): void
|
|
send(notification: Notification, options?: SendOptions): Promise<NotificationResult[]>
|
|
sendBatch(notifications: Notification[], options?: BatchOptions): AsyncGenerator<NotificationResult[]>
|
|
}
|
|
|
|
interface NotificationServiceOptions {
|
|
channels?: NotificationChannel[]
|
|
fallbackChain?: ChannelType[] // try channels in order until one succeeds
|
|
logger?: LoggerLike
|
|
bus?: EventBusLike
|
|
}
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type NotificationErrorCode =
|
|
| 'NOTIF_NO_CHANNEL'
|
|
| 'NOTIF_ALL_FAILED'
|
|
| 'NOTIF_TEMPLATE_NOT_FOUND'
|
|
| 'NOTIF_RECIPIENT_INVALID'
|
|
| 'NOTIF_SUPPRESSED'
|
|
| 'NOTIF_SEND_FAILED'
|
|
| 'NOTIF_ABORTED'
|
|
```
|
|
|
|
---
|
|
|
|
## Genesis additions
|
|
|
|
1. **`NotificationError`** extends `SuaveplanError` with seven stable codes.
|
|
2. **Zod schemas** for `Notification`, `NotificationRecipient`, `ChannelPreferences`, `NotificationResult`, `NotificationServiceOptions`.
|
|
3. **Preference-aware routing** — before dispatch, checks `recipient.preferences[channel]`; `false` → `skipped` status.
|
|
4. **Suppression integration** — email and SMS channels call `@suaveplan/suppression` before dispatch; suppressed → `suppressed` status.
|
|
5. **Fallback chain** — if primary channel fails, try next channel in `fallbackChain` until one succeeds or all fail.
|
|
6. **OTel instrumentation** — counter `notification.send_total` with attributes `notification.channel`, `notification.status`; histogram `notification.send_duration_ms`.
|
|
7. **Property-based tests** — channel preference filter correctly skips opted-out channels for arbitrary preference maps.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
universal/messaging/notification-channel/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/
|
|
index.ts
|
|
types/
|
|
common.ts
|
|
common.md
|
|
core/
|
|
notification-service/
|
|
notification-service.ts
|
|
notification-service.md
|
|
notification-service.types.ts
|
|
notification-service.test.ts
|
|
index.ts
|
|
notification-router/
|
|
notification-router.ts
|
|
notification-router.md
|
|
notification-router.test.ts
|
|
index.ts
|
|
channels/
|
|
email-channel/
|
|
email-channel.ts
|
|
email-channel.md
|
|
email-channel.test.ts
|
|
index.ts
|
|
sms-channel/
|
|
sms-channel.ts
|
|
sms-channel.md
|
|
sms-channel.test.ts
|
|
index.ts
|
|
in-app-channel/
|
|
in-app-channel.ts
|
|
in-app-channel.md
|
|
in-app-channel.test.ts
|
|
index.ts
|
|
webhook-channel/
|
|
webhook-channel.ts
|
|
webhook-channel.md
|
|
webhook-channel.test.ts
|
|
index.ts
|
|
__benchmarks__/
|
|
notification-channel.bench.ts
|
|
tests/
|
|
integration.test.ts
|
|
property.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream consumers**: any server-side notification dispatch service.
|
|
|
|
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/templates`, `@suaveplan/email-templates`, `@suaveplan/retry`, `@suaveplan/suppression`.
|