# 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/`.