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

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