Initial Commit

openspec/changes/enterprise-delivery-tracking/tasks.md

@@ -0,0 +1,71 @@
+# Tasks: enterprise-delivery-tracking
+
+**Change ID**: enterprise-delivery-tracking
+**Package**: `@suaveplan/delivery-tracking`
+**Target path**: `universal/email/delivery-tracking`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/suppression`, `@suaveplan/crypto`, `@suaveplan/pagination`
+
+---
+
+## 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/email/delivery-tracking/` 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` — `DeliveryEvent`, `DeliveryEventType`, `BounceType`, `DeliveryAnalytics`, `DeliveryEventInput`, `ListOptions`, `MemoryTrackerOptions`, `WebhookNormalizeOptions`.
+- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
+- [ ] `src/error-codes.ts` — `DeliveryTrackingErrorCode` (5 codes), metadata, register, eager call.
+- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
+
+---
+
+## 3. Core modules
+
+- [ ] **`src/core/memory-tracker/`** — `createMemoryDeliveryTracker(options)`: implements `DeliveryTracker` in memory. On `record(event)` with type `bounced` (hard) or `complained`, automatically calls `@suaveplan/suppression` to add recipient. Tests: record/get, listByMessage, listByRecipient pagination, analytics aggregation, auto-suppression on bounce.
+- [ ] **`src/analytics/analytics-aggregator/`** — `aggregateAnalytics(events): DeliveryAnalytics`: computes all rate fields. Tests: empty set, all delivered, mixed, opened/clicked subset.
+- [ ] **`src/webhook/signature-verifier/`** — `verifyWebhookSignature(body, secret, timestamp, signature, options)`: constant-time HMAC via `@suaveplan/crypto`; rejects if `|now - timestamp| > clockSkewSeconds`. Tests: valid, tampered body, expired timestamp, missing timestamp.
+- [ ] **`src/webhook/webhook-normalizer/`** — `normalizeWebhookPayload(body, headers, options)`: dispatches to per-provider normaliser based on `providerHint` or header fingerprinting. Implements normalizers for: generic (attempts to extract `event`, `email`, `timestamp` keys), SendGrid, Mailgun, SES, Postmark. Each normaliser maps provider event types to `DeliveryEventType`. Tests: one happy-path test per provider; unknown provider graceful fall-back to generic.
+
+---
+
+## 4. OTel instrumentation
+
+- [ ] Counter `delivery.event_total` with attribute `delivery.event_type` on every `record()` call.
+- [ ] Histogram `delivery.analytics_duration_ms` on `analytics()`.
+
+---
+
+## 5. Property-based tests (`tests/property.test.ts`)
+
+- [ ] Analytics rate calculations: `deliveryRate = delivered / sent` for arbitrary event sets (no NaN when sent=0).
+- [ ] Suppression auto-propagation: for any `bounced` (hard) event, the recipient always appears in the suppression store.
+
+---
+
+## 6. Benchmarks (`src/__benchmarks__/delivery-tracking.bench.ts`)
+
+- [ ] `record` 10 000 events sequentially.
+- [ ] `analytics` over 10 000 events.
+
+---
+
+## 7. Docs + verify
+
+- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/delivery-tracking` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/delivery-tracking` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/delivery-tracking`.
+- [ ] Archive: `openspec/archive/2026-04-24-enterprise-delivery-tracking/`.