Initial Commit
This commit is contained in:
195
openspec/changes/enterprise-delivery-tracking/proposal.md
Normal file
195
openspec/changes/enterprise-delivery-tracking/proposal.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# OpenSpec Change: enterprise-delivery-tracking
|
||||
|
||||
- **Change ID**: enterprise-delivery-tracking
|
||||
- **Package**: `@suaveplan/delivery-tracking`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/email/delivery-tracking`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/delivery-tracking.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/delivery-tracking` on the genesis branch from scratch at enterprise quality. The package provides channel-agnostic delivery event tracking: a typed `DeliveryEvent` model covering all SMTP/webhook status transitions (`queued`, `sent`, `delivered`, `bounced`, `complained`, `unsubscribed`, `opened`, `clicked`), a `DeliveryTracker` facade with pluggable store adapters, webhook payload normalization for major ESP providers (generic interface — no provider SDK deps), bounce classification (hard/soft/transient), unsubscribe propagation to `@suaveplan/suppression`, and per-campaign/per-recipient analytics aggregation. Genesis adds structured errors, Zod schemas, OTel instrumentation, 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:^`) | `DeliveryTrackingError`; `DLVR.*` error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `EventBusLike`, `StorageLike` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Delivery event propagation |
|
||||
| `@suaveplan/suppression` (`workspace:^`) | Unsubscribe/bounce → suppression list write |
|
||||
| `@suaveplan/crypto` (`workspace:^`) | HMAC-SHA256 webhook signature verification |
|
||||
| `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 DeliveryEventType =
|
||||
| 'queued' | 'sent' | 'delivered' | 'deferred'
|
||||
| 'bounced' | 'complained' | 'unsubscribed'
|
||||
| 'opened' | 'clicked'
|
||||
|
||||
type BounceType = 'hard' | 'soft' | 'transient'
|
||||
|
||||
interface DeliveryEvent {
|
||||
id: string
|
||||
messageId: string
|
||||
campaignId?: string
|
||||
recipientEmail: string
|
||||
type: DeliveryEventType
|
||||
timestamp: Date
|
||||
bounceType?: BounceType
|
||||
bounceCode?: string
|
||||
clickUrl?: string
|
||||
userAgent?: string
|
||||
ipAddress?: string
|
||||
metadata: Record<string, unknown>
|
||||
}
|
||||
|
||||
interface DeliveryAnalytics {
|
||||
campaignId: string
|
||||
total: number
|
||||
sent: number
|
||||
delivered: number
|
||||
bounced: number
|
||||
complained: number
|
||||
unsubscribed: number
|
||||
opened: number
|
||||
clicked: number
|
||||
deliveryRate: number
|
||||
openRate: number
|
||||
clickRate: number
|
||||
bounceRate: number
|
||||
}
|
||||
```
|
||||
|
||||
### `DeliveryTracker`
|
||||
|
||||
```ts
|
||||
interface DeliveryTracker {
|
||||
record(event: DeliveryEventInput): Promise<DeliveryEvent>
|
||||
get(eventId: string): Promise<DeliveryEvent | undefined>
|
||||
listByMessage(messageId: string): Promise<DeliveryEvent[]>
|
||||
listByRecipient(email: string, options?: ListOptions): Promise<PaginatedResult<DeliveryEvent>>
|
||||
analytics(campaignId: string): Promise<DeliveryAnalytics>
|
||||
}
|
||||
|
||||
function createMemoryDeliveryTracker(options?: MemoryTrackerOptions): DeliveryTracker
|
||||
```
|
||||
|
||||
### Webhook normalizer
|
||||
|
||||
```ts
|
||||
interface WebhookNormalizeOptions {
|
||||
secret?: string // HMAC secret for signature verification
|
||||
providerHint?: string // 'sendgrid' | 'mailgun' | 'ses' | 'postmark' | 'generic'
|
||||
}
|
||||
|
||||
function normalizeWebhookPayload(
|
||||
body: unknown,
|
||||
headers: Record<string, string>,
|
||||
options?: WebhookNormalizeOptions
|
||||
): DeliveryEventInput[]
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type DeliveryTrackingErrorCode =
|
||||
| 'DLVR_EVENT_NOT_FOUND'
|
||||
| 'DLVR_INVALID_PAYLOAD'
|
||||
| 'DLVR_SIGNATURE_FAILED'
|
||||
| 'DLVR_STORE_FAILED'
|
||||
| 'DLVR_ANALYTICS_FAILED'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **`DeliveryTrackingError`** extends `SuaveplanError` with five stable codes.
|
||||
2. **Zod schemas** for `DeliveryEvent`, `DeliveryAnalytics`, `WebhookNormalizeOptions`, all provider payload shapes.
|
||||
3. **Suppression auto-propagation** — `bounced` (hard) and `complained` events automatically call `@suaveplan/suppression` to add the recipient.
|
||||
4. **Webhook signature verification** — constant-time HMAC via `@suaveplan/crypto`; configurable clock-skew window.
|
||||
5. **OTel instrumentation** — counter `delivery.event_total` with attribute `delivery.event_type`; histogram `delivery.analytics_duration_ms`.
|
||||
6. **Property-based tests** — analytics rate calculations for arbitrary event sets.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/email/delivery-tracking/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
delivery-tracker/
|
||||
delivery-tracker.ts
|
||||
delivery-tracker.md
|
||||
delivery-tracker.types.ts
|
||||
delivery-tracker.test.ts
|
||||
index.ts
|
||||
memory-tracker/
|
||||
memory-tracker.ts
|
||||
memory-tracker.md
|
||||
memory-tracker.test.ts
|
||||
index.ts
|
||||
analytics/
|
||||
analytics-aggregator/
|
||||
analytics-aggregator.ts
|
||||
analytics-aggregator.md
|
||||
analytics-aggregator.test.ts
|
||||
index.ts
|
||||
webhook/
|
||||
webhook-normalizer/
|
||||
webhook-normalizer.ts
|
||||
webhook-normalizer.md
|
||||
webhook-normalizer.test.ts
|
||||
index.ts
|
||||
signature-verifier/
|
||||
signature-verifier.ts
|
||||
signature-verifier.md
|
||||
signature-verifier.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
delivery-tracking.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream consumers**: `@suaveplan/campaigns`, any server-side email dispatch service.
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/suppression`, `@suaveplan/crypto`, `@suaveplan/pagination`.
|
||||
71
openspec/changes/enterprise-delivery-tracking/tasks.md
Normal file
71
openspec/changes/enterprise-delivery-tracking/tasks.md
Normal file
@@ -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/`.
|
||||
Reference in New Issue
Block a user