Initial Commit
This commit is contained in:
201
openspec/changes/enterprise-campaigns/proposal.md
Normal file
201
openspec/changes/enterprise-campaigns/proposal.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# OpenSpec Change: enterprise-campaigns
|
||||
|
||||
- **Change ID**: enterprise-campaigns
|
||||
- **Package**: `@suaveplan/campaigns`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/email/campaigns`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/campaigns.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/campaigns` on the genesis branch from scratch at enterprise quality. The package provides email campaign orchestration: campaign lifecycle state machine (`draft` → `scheduled` → `sending` → `sent` / `cancelled` / `failed`), audience resolution via `@suaveplan/audience-rules`, template selection via `@suaveplan/email-templates`, per-recipient variable injection, send-rate throttling with configurable concurrency, schedule management (immediate, future ISO-8601, recurring via cron expression), campaign analytics aggregation, and A/B variant support. Genesis adds structured errors, Zod schemas, OTel instrumentation, `AbortSignal` cancellation, idempotent send via `@suaveplan/idempotency`, and retry with circuit breaker via `@suaveplan/retry`.
|
||||
|
||||
---
|
||||
|
||||
## 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:^`) | `CampaignError`; `CAMPAIGN.*` error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `EventBusLike` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Campaign lifecycle event bus |
|
||||
| `@suaveplan/email-templates` (`workspace:^`) | Template rendering per recipient |
|
||||
| `@suaveplan/audience-rules` (`workspace:^`) | Audience segment resolution |
|
||||
| `@suaveplan/idempotency` (`workspace:^`) | Per-recipient idempotency key guard |
|
||||
| `@suaveplan/retry` (`workspace:^`) | Retry + circuit breaker for delivery calls |
|
||||
| `@suaveplan/suppression` (`workspace:^`) | Suppression list check before send |
|
||||
| `zod` (`catalog:forms`) | Option schema validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters + histograms |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
type CampaignStatus =
|
||||
| 'draft' | 'scheduled' | 'sending' | 'sent' | 'cancelled' | 'failed'
|
||||
|
||||
interface Campaign {
|
||||
id: string
|
||||
name: string
|
||||
templateName: string
|
||||
audienceRuleId: string
|
||||
schedule: CampaignSchedule
|
||||
status: CampaignStatus
|
||||
abVariants?: AbVariant[]
|
||||
metadata: Record<string, unknown>
|
||||
createdAt: Date
|
||||
updatedAt: Date
|
||||
}
|
||||
|
||||
interface CampaignSchedule {
|
||||
type: 'immediate' | 'at' | 'recurring'
|
||||
at?: string // ISO-8601 for type:'at'
|
||||
cron?: string // cron expression for type:'recurring'
|
||||
timezone?: string
|
||||
}
|
||||
|
||||
interface AbVariant {
|
||||
name: string
|
||||
templateName: string
|
||||
fraction: number // 0–1, fractions must sum to ≤1
|
||||
}
|
||||
|
||||
interface CampaignSendOptions {
|
||||
concurrency?: number // max parallel sends; default 10
|
||||
ratePerSecond?: number // max sends/second; default 100
|
||||
signal?: AbortSignal
|
||||
dryRun?: boolean
|
||||
}
|
||||
|
||||
interface CampaignAnalytics {
|
||||
campaignId: string
|
||||
sent: number
|
||||
failed: number
|
||||
suppressed: number
|
||||
durationMs: number
|
||||
}
|
||||
```
|
||||
|
||||
### `CampaignManager`
|
||||
|
||||
```ts
|
||||
class CampaignManager {
|
||||
constructor(options: CampaignManagerOptions)
|
||||
create(draft: Omit<Campaign, 'id' | 'status' | 'createdAt' | 'updatedAt'>): Campaign
|
||||
schedule(id: string, schedule: CampaignSchedule): Campaign
|
||||
send(id: string, options?: CampaignSendOptions): Promise<CampaignAnalytics>
|
||||
cancel(id: string): Campaign
|
||||
get(id: string): Campaign | undefined
|
||||
list(filter?: CampaignFilter): Campaign[]
|
||||
}
|
||||
|
||||
interface CampaignManagerOptions {
|
||||
sender: CampaignSender // injectable delivery adapter
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
bus?: EventBusLike
|
||||
}
|
||||
|
||||
interface CampaignSender {
|
||||
send(recipient: string, subject: string, html: string, text: string): Promise<void>
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type CampaignErrorCode =
|
||||
| 'CAMPAIGN_NOT_FOUND'
|
||||
| 'CAMPAIGN_INVALID_TRANSITION'
|
||||
| 'CAMPAIGN_SEND_FAILED'
|
||||
| 'CAMPAIGN_TEMPLATE_NOT_FOUND'
|
||||
| 'CAMPAIGN_AUDIENCE_FAILED'
|
||||
| 'CAMPAIGN_ABORTED'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **`CampaignError`** extends `SuaveplanError` with six stable codes.
|
||||
2. **Zod schemas** for `Campaign`, `CampaignSchedule`, `AbVariant`, `CampaignSendOptions`, `CampaignAnalytics`.
|
||||
3. **A/B variant support** — variants are bucketed deterministically by recipient hash (FNV-1a) against configured fractions.
|
||||
4. **Suppression list integration** — calls `@suaveplan/suppression` before every send; suppressed recipients are counted in analytics without being sent to.
|
||||
5. **OTel instrumentation** — span `campaign.send`, counter `campaign.send_total`, histogram `campaign.send_duration_ms`, attributes `campaign.id`, `campaign.status`, `campaign.recipient_count`.
|
||||
6. **Property-based tests** — A/B bucketing distribution, state machine transition invariants.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/email/campaigns/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
campaign-manager/
|
||||
campaign-manager.ts
|
||||
campaign-manager.md
|
||||
campaign-manager.types.ts
|
||||
campaign-manager.test.ts
|
||||
index.ts
|
||||
campaign-fsm/
|
||||
campaign-fsm.ts
|
||||
campaign-fsm.md
|
||||
campaign-fsm.test.ts
|
||||
index.ts
|
||||
ab-bucketing/
|
||||
ab-bucketing.ts
|
||||
ab-bucketing.md
|
||||
ab-bucketing.test.ts
|
||||
index.ts
|
||||
scheduling/
|
||||
schedule-parser/
|
||||
schedule-parser.ts
|
||||
schedule-parser.md
|
||||
schedule-parser.test.ts
|
||||
index.ts
|
||||
analytics/
|
||||
campaign-analytics/
|
||||
campaign-analytics.ts
|
||||
campaign-analytics.md
|
||||
campaign-analytics.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
campaigns.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream consumers**: any server-side campaign dispatch service.
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/email-templates`, `@suaveplan/audience-rules`, `@suaveplan/idempotency`, `@suaveplan/retry`, `@suaveplan/suppression`.
|
||||
70
openspec/changes/enterprise-campaigns/tasks.md
Normal file
70
openspec/changes/enterprise-campaigns/tasks.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# Tasks: enterprise-campaigns
|
||||
|
||||
**Change ID**: enterprise-campaigns
|
||||
**Package**: `@suaveplan/campaigns`
|
||||
**Target path**: `universal/email/campaigns`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/email-templates`, `@suaveplan/audience-rules`, `@suaveplan/idempotency`, `@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/email/campaigns/` 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` — `Campaign`, `CampaignStatus`, `CampaignSchedule`, `AbVariant`, `CampaignSendOptions`, `CampaignAnalytics`, `CampaignFilter`, `CampaignSender`, `CampaignManagerOptions`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — `CampaignErrorCode` (6 codes), metadata, register, eager call.
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core modules
|
||||
|
||||
- [ ] **`src/core/campaign-fsm/`** — `CampaignFsm`: defines valid transitions between `CampaignStatus` values; illegal transitions throw `CAMPAIGN_INVALID_TRANSITION`. Tests: all valid paths, two invalid transition attempts.
|
||||
- [ ] **`src/core/ab-bucketing/`** — `bucketRecipient(email, variants): AbVariant | undefined`: FNV-1a hash of email, compare against cumulative fraction bounds. Tests: determinism (same input → same bucket), distribution across 10 000 random emails is within 5% of configured fraction.
|
||||
- [ ] **`src/scheduling/schedule-parser/`** — `parseSchedule(schedule, clock)`: returns next fire `Date` for immediate/at/recurring. Validates cron expressions (5-field). Tests: immediate → `now`, at → future date, recurring → next slot, invalid cron throws.
|
||||
- [ ] **`src/core/campaign-manager/`** — `CampaignManager`: `create`, `schedule`, `send`, `cancel`, `get`, `list`. `send` iterates audience from `@suaveplan/audience-rules`, checks suppression per recipient, renders template per recipient (optionally with A/B variant), calls `CampaignSender.send`. Wraps each recipient delivery in idempotency guard. `AbortSignal` cancel mid-send. Tests: send happy path, abort mid-send, suppressed recipient is counted not sent, A/B variant selection, analytics returned correctly.
|
||||
- [ ] **`src/analytics/campaign-analytics/`** — `aggregateResults(results): CampaignAnalytics`. Tests: all-sent, mixed-failure, all-suppressed.
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] `send`: span `campaign.send` with attributes `campaign.id`, `campaign.recipient_count`; counter `campaign.send_total`; histogram `campaign.send_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Property-based tests (`tests/property.test.ts`)
|
||||
|
||||
- [ ] A/B bucketing: for arbitrary variant fractions summing to ≤1, `bucketRecipient` always returns a variant within the configured set or `undefined`.
|
||||
- [ ] FSM: any reachable path from `draft` reaches a terminal state (`sent`, `cancelled`, `failed`) in ≤4 transitions.
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks (`src/__benchmarks__/campaigns.bench.ts`)
|
||||
|
||||
- [ ] `bucketRecipient` for 100 000 recipients.
|
||||
|
||||
---
|
||||
|
||||
## 7. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/campaigns` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/campaigns` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/campaigns`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-campaigns/`.
|
||||
Reference in New Issue
Block a user