suaveplan/openspec/changes/enterprise-notification-channel/tasks.md

Tasks: enterprise-notification-channel

Change ID: enterprise-notification-channel Package: @suaveplan/notification-channel Target path: universal/messaging/notification-channel Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/templates, @suaveplan/email-templates, @suaveplan/retry, @suaveplan/suppression

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create universal/messaging/notification-channel/ with src/, tests/, src/__benchmarks__/ and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, correct exports map, dependencies, and devDependencies.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• src/types/common.ts — ChannelType, Notification, NotificationRecipient, ChannelPreferences, NotificationResult, NotificationChannel (interface), ChannelSendOptions, NotificationServiceOptions, SendOptions, BatchOptions.
• src/types/common.md (≥200 words, both examples, API reference).
• src/error-codes.ts — NotificationErrorCode (7 codes), metadata, register, eager call.
• src/types/schemas.ts + schemas.md — Zod schemas.

---

3. Core modules

• src/core/notification-router/ — NotificationRouter: given a Notification and registered channels, selects channels from notification.channels that are available for the recipient, not opted out (ChannelPreferences), and not suppressed. Returns ChannelType[] to dispatch. Tests: preference-filtered, suppressed email excluded, fallback chain triggered.
• src/channels/email-channel/ — EmailChannel implements NotificationChannel: type='email'; isAvailableFor checks recipient.email is set; send renders via @suaveplan/email-templates, calls injected emailSender. Tests: happy path, missing email returns isAvailableFor=false, suppressed recipient skipped.
• src/channels/sms-channel/ — SmsChannel implements NotificationChannel: type='sms'; isAvailableFor checks recipient.phone is set; send renders body via @suaveplan/templates, calls injected smsSender. Tests: happy path, missing phone not available.
• src/channels/in-app-channel/ — InAppChannel implements NotificationChannel: stores notifications in memory (injectable store); isAvailableFor always true when recipient.id is set. Tests: send adds to store, list by recipient.
• src/channels/webhook-channel/ — WebhookChannel implements NotificationChannel: type configurable; send POSTs JSON payload to configured webhook URL via injectable fetch with HMAC signature. Tests: POST called with correct JSON, signature header present.
• src/core/notification-service/ — NotificationService: register(channel), send(notification, options) — calls router to get channels, dispatches in parallel (or series for fallback chain), collects results. sendBatch yields results per notification. Tests: all channels succeed, one fails and fallback invoked, all failed → NOTIF_ALL_FAILED, AbortSignal cancel.

---

4. OTel instrumentation

• Counter notification.send_total with attributes notification.channel, notification.status; histogram notification.send_duration_ms.

---

5. Property-based tests (tests/property.test.ts)

• Preference filter: for arbitrary ChannelPreferences maps and channel lists, router only selects channels with preference !== false.

---

6. Benchmarks (src/__benchmarks__/notification-channel.bench.ts)

• NotificationRouter.selectChannels for 100 000 notifications with 4 registered channels.

---

7. Docs + verify

• One .md per implementation file (≥200 words, both examples, API reference). Root README.md.
• bunx turbo lint typecheck test --filter=@suaveplan/notification-channel — green.
• bunx turbo test:coverage --filter=@suaveplan/notification-channel — 100%.
• bun scripts/publish.ts --package @suaveplan/notification-channel.
• Archive: openspec/archive/2026-04-24-enterprise-notification-channel/.