299 lines
13 KiB
Markdown
299 lines
13 KiB
Markdown
# `api-plugin-campaigns` capability
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Package shape and tier
|
|
|
|
The package `@suaveplan/api-plugin-campaigns` SHALL be a server-tier Hono +
|
|
OpenAPI plugin published under the genesis monorepo at
|
|
`packages/api-stack/api/api-plugin-campaigns/`, version `0.1.0`,
|
|
`"sideEffects": false`.
|
|
|
|
#### Scenario: Workspace discovery
|
|
|
|
- **GIVEN** a `bunx turbo --filter=@suaveplan/api-plugin-campaigns` invocation
|
|
- **THEN** the workspace SHALL resolve to
|
|
`packages/api-stack/api/api-plugin-campaigns/`.
|
|
|
|
### Requirement: Error namespace `CAMPAIGNS_API.*`
|
|
|
|
The package SHALL export a `CAMPAIGNS_API_CODES` registry built via
|
|
`defineCodes` from `@suaveplan/error`, and a `CampaignsApiError` subclass of
|
|
`SuaveplanError` with an explicit public constructor delegating to `super`.
|
|
|
|
#### Scenario: Code namespacing
|
|
|
|
- **WHEN** any entry of `CAMPAIGNS_API_CODES` is read
|
|
- **THEN** the value SHALL begin with the prefix `"CAMPAIGNS_API."`.
|
|
|
|
### Requirement: OTel instrument bundle
|
|
|
|
The package SHALL bind an OpenTelemetry meter under
|
|
`"@suaveplan/api-plugin-campaigns"` exposing at minimum a request-count
|
|
counter and a request-duration histogram, with a cached factory function and
|
|
a reset hook for tests.
|
|
|
|
#### Scenario: Lazy binding
|
|
|
|
- **WHEN** `getCampaignsApiInstruments()` is called after a fresh
|
|
`MeterProvider` is installed and `resetCampaignsApiInstruments()` has been
|
|
invoked
|
|
- **THEN** the returned bundle SHALL be bound to the new provider.
|
|
|
|
### Requirement: Plugin factory
|
|
|
|
The package SHALL export `createCampaignsPlugin(options)` returning a
|
|
`PluginDescriptor` from `@suaveplan/api-plugin` with `name === "campaigns"`,
|
|
`version === "0.1.0"`, and `dependencies` including at minimum
|
|
`"database"`, `"auth"`, and `"contacts"`.
|
|
|
|
#### Scenario: Option validation
|
|
|
|
- **WHEN** `createCampaignsPlugin(options)` is called with options that fail
|
|
the Zod options schema
|
|
- **THEN** the function SHALL throw `CampaignsApiError` carrying code
|
|
`CAMPAIGNS_API.INVALID_OPTIONS` with the original `ZodError` attached as
|
|
`cause`.
|
|
|
|
### Requirement: Chunked migration discipline
|
|
|
|
The migration SHALL ship in three chunks (foundation A, repositories B,
|
|
routes C). At every chunk boundary the package SHALL pass lint, typecheck,
|
|
test, and 100/100/100/100 coverage on the modules shipped to date.
|
|
|
|
#### Scenario: Chunk-A `onInit` is a no-op placeholder
|
|
|
|
- **GIVEN** the Chunk-A milestone
|
|
- **WHEN** the plugin is registered on a host
|
|
- **THEN** `onInit` SHALL complete without registering repositories or routes,
|
|
and that no-op behaviour SHALL be documented in `plugin.md` as the
|
|
Chunk-A-correct state.
|
|
|
|
### Requirement: Campaign repository (Chunk B)
|
|
|
|
The package SHALL export a `SurrealCampaignRepository` class implementing the
|
|
`CampaignStore` contract from `@suaveplan/campaigns`. The repository SHALL
|
|
issue every database call through `SurrealAdapter.query<T>(sql, params)`
|
|
using positional `$p0`/`$p1`/... placeholders per the genesis Surreal idiom,
|
|
and SHALL wrap every adapter exception in `CampaignsApiError` with one of
|
|
`CAMPAIGNS_API.DB_UNAVAILABLE`, `CAMPAIGNS_API.CAMPAIGN_NOT_FOUND`, or
|
|
`CAMPAIGNS_API.INVALID_INPUT`.
|
|
|
|
**Verified by:** `packages/api-stack/api/api-plugin-campaigns/src/repositories/campaign/campaign.test.ts`
|
|
(24 cases covering INSERT, SELECT-by-id, UPDATE, DELETE, listing with paging,
|
|
`updateStats` MERGE, `updateStatus` SET, schema validation, custom table
|
|
overrides, and adapter-error wrapping).
|
|
|
|
#### Scenario: Positional SurQL binding
|
|
|
|
- **WHEN** `SurrealCampaignRepository.create(campaign)` runs
|
|
- **THEN** the resulting SurQL SHALL contain `INSERT INTO campaign`, the
|
|
placeholder list SHALL use `$p0`/`$p1`/... in registration order, and the
|
|
campaign's `tenantId` SHALL appear at `params[1]`.
|
|
|
|
#### Scenario: Adapter-error wrapping
|
|
|
|
- **GIVEN** the adapter throws on a SELECT
|
|
- **WHEN** `getById("c1")` runs
|
|
- **THEN** the call SHALL throw `CampaignsApiError` carrying
|
|
`CAMPAIGNS_API.DB_UNAVAILABLE` with the original error attached as `cause`.
|
|
|
|
#### Scenario: Missing-row semantics for updateStats
|
|
|
|
- **GIVEN** the SurrealDB UPDATE returns no rows
|
|
- **WHEN** `updateStats(id, stats)` runs
|
|
- **THEN** the call SHALL throw `CampaignsApiError` carrying
|
|
`CAMPAIGNS_API.CAMPAIGN_NOT_FOUND` rather than a generic `Error`.
|
|
|
|
### Requirement: Campaign suppression store (Chunk B)
|
|
|
|
The package SHALL export a local `CampaignSuppressionStore` interface and a
|
|
`SurrealCampaignSuppressionRepository` implementation, plus a reference
|
|
`InMemoryCampaignSuppressionStore`. The local interface SHALL be tenant +
|
|
channel scoped — the `(tenantId, channel, channelValue)` triple is the
|
|
natural primary key — and the package SHALL NOT depend on
|
|
`@suaveplan/suppression`, which is email-only and therefore not a fit for
|
|
the campaigns plugin's multi-channel domain.
|
|
|
|
**Verified by:**
|
|
`packages/api-stack/api/api-plugin-campaigns/src/repositories/suppression/suppression.test.ts`
|
|
(SurrealDB implementation) and
|
|
`packages/api-stack/api/api-plugin-campaigns/src/repositories/suppression/suppression-memory.test.ts`
|
|
(in-memory reference) — together covering `add`, `remove`, `check`, `list`,
|
|
`count`, `removeByChannelValue`, duplicate detection, tenant guards, and
|
|
schema validation across both backends.
|
|
|
|
#### Scenario: Channel-scoped duplicate detection
|
|
|
|
- **GIVEN** an entry exists for `(t1, email, user@example.com)`
|
|
- **WHEN** `add({ tenantId: "t1", channel: "email", channelValue: "user@example.com", reason: "bounce" })` runs
|
|
- **THEN** the call SHALL throw `CampaignsApiError` carrying
|
|
`CAMPAIGNS_API.DUPLICATE_SUPPRESSION`, AND a subsequent
|
|
`add({ tenantId: "t1", channel: "sms", channelValue: "user@example.com", reason: "bounce" })`
|
|
SHALL succeed (different channel, same value).
|
|
|
|
#### Scenario: Empty tenant rejection
|
|
|
|
- **WHEN** any read method (`check`, `list`, `count`,
|
|
`removeByChannelValue`) is invoked with `tenantId === ""`
|
|
- **THEN** the call SHALL throw `CampaignsApiError` carrying
|
|
`CAMPAIGNS_API.TENANT_REQUIRED`.
|
|
|
|
### Requirement: Error namespace extension (Chunk B)
|
|
|
|
The Chunk-B repositories SHALL extend `CAMPAIGNS_API_CODES` additively with
|
|
six new codes: `CAMPAIGN_NOT_FOUND`, `SUPPRESSION_NOT_FOUND`,
|
|
`INVALID_INPUT`, `DB_UNAVAILABLE`, `DUPLICATE_SUPPRESSION`,
|
|
`TENANT_REQUIRED`. The registry MUST remain a single `defineCodes` call —
|
|
no parallel namespace.
|
|
|
|
**Verified by:**
|
|
`packages/api-stack/api/api-plugin-campaigns/src/error-codes/error-codes.test.ts`
|
|
asserts the full code key set and that every new code begins with
|
|
`"CAMPAIGNS_API."`.
|
|
|
|
#### Scenario: Single registry, additive extension
|
|
|
|
- **WHEN** any new code is added in Chunks B or C
|
|
- **THEN** the code SHALL appear inside the existing
|
|
`defineCodes("CAMPAIGNS_API", [...])` call, AND
|
|
`Object.keys(CAMPAIGNS_API_CODES)` SHALL equal the union of every
|
|
registered key — no second registry exists.
|
|
|
|
### Requirement: Campaign route surface (Chunk C)
|
|
|
|
The package SHALL expose a `buildCampaignRoutes` aggregator returning a
|
|
readonly array of `PluginRouteEntry` values mounting the 12 canonical
|
|
`/campaigns/*` endpoints (list, create, get, update, delete, send, pause,
|
|
cancel, duplicate, test, stats, events) in a deterministic, documented
|
|
order. Every CRUD handler SHALL enforce tenant scoping through
|
|
`requireTenant`, cross-tenant lookups SHALL surface as
|
|
`CAMPAIGNS_API.CAMPAIGN_NOT_FOUND` (HTTP 404), and Zod validation
|
|
failures on request bodies SHALL surface as
|
|
`CAMPAIGNS_API.INVALID_INPUT` (HTTP 400). Action routes
|
|
(`/send`, `/pause`, `/cancel`) SHALL drive transitions through
|
|
`CampaignStateMachine` from `@suaveplan/campaigns`; invalid transitions
|
|
SHALL surface as `CAMPAIGNS_API.INVALID_STATE_TRANSITION` (HTTP 409).
|
|
Reporting routes (`/stats`, `/events`) SHALL consume the
|
|
`deliveryEventStore` context slot.
|
|
|
|
**Verified by:**
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/campaigns/crud-routes.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/campaigns/action-routes.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/campaigns/build-routes.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/campaigns/schemas.test.ts`
|
|
(80+ cases together covering happy paths, 401/404/409/400/500 surfaces,
|
|
state-machine transitions, duplicate semantics, delivery-event
|
|
reporting, and canonical-order assertions).
|
|
|
|
#### Scenario: Invalid state transition
|
|
|
|
- **GIVEN** a campaign in status `completed`
|
|
- **WHEN** `POST /campaigns/:id/send` runs
|
|
- **THEN** the response SHALL be HTTP 409 carrying body
|
|
`{ code: "CAMPAIGNS_API.INVALID_STATE_TRANSITION", ... }`.
|
|
|
|
#### Scenario: Cross-tenant lookup leak prevention
|
|
|
|
- **GIVEN** a campaign owned by tenant `other`
|
|
- **WHEN** the caller authenticated as tenant `t` issues
|
|
`GET /campaigns/:id`
|
|
- **THEN** the response SHALL be HTTP 404 carrying body
|
|
`{ code: "CAMPAIGNS_API.CAMPAIGN_NOT_FOUND", ... }` — identical to the
|
|
response for a non-existent id, so no information about cross-tenant
|
|
campaigns leaks.
|
|
|
|
### Requirement: Suppression route surface (Chunk C)
|
|
|
|
The package SHALL expose a `buildSuppressionRoutes` aggregator returning
|
|
the 4 canonical `/suppression/*` endpoints in canonical order (list,
|
|
check, create, delete). Every handler SHALL enforce `requireTenant`
|
|
before touching the suppression store. The `GET /suppression/check`
|
|
endpoint SHALL accept `channel` and `channelValue` as required query
|
|
parameters and return `{ suppressed: boolean, entry: ... | null }` so
|
|
sender pipelines can short-circuit deliveries with a single read.
|
|
`DELETE /suppression/:id` SHALL return HTTP 404 carrying
|
|
`CAMPAIGNS_API.SUPPRESSION_NOT_FOUND` when the entry does not exist.
|
|
|
|
**Verified by:**
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/suppression/routes.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/suppression/schemas.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/suppression/build-routes.test.ts`
|
|
(20+ cases covering list/check/add/delete happy paths, 401/400/404/500
|
|
surfaces, and canonical-order assertions).
|
|
|
|
#### Scenario: Point-lookup suppression check
|
|
|
|
- **GIVEN** an entry exists for `(t1, email, user@example.com)`
|
|
- **WHEN** `GET /suppression/check?channel=email&channelValue=user@example.com`
|
|
runs
|
|
- **THEN** the response SHALL be HTTP 200 with body
|
|
`{ data: { suppressed: true, entry: { ... } } }`.
|
|
|
|
### Requirement: Webhook route surface (Chunk C)
|
|
|
|
The package SHALL expose a `buildWebhookRoutes` aggregator returning the
|
|
2 canonical `/webhooks/*` endpoints (delivery ingest and unsubscribe
|
|
token decoder). `POST /webhooks/delivery` SHALL persist the event via
|
|
the `deliveryEventStore` and additionally insert a
|
|
`CampaignSuppressionEntry` when the event type is `unsubscribed`,
|
|
`bounced`, or `complained`. The fan-out SHALL be idempotent — a
|
|
duplicate event SHALL NOT raise `DUPLICATE_SUPPRESSION` at the route
|
|
layer. Zod-validation failure on the delivery body SHALL surface as
|
|
`CAMPAIGNS_API.WEBHOOK_REJECTED`; token decode failure on the
|
|
unsubscribe path SHALL surface as
|
|
`CAMPAIGNS_API.INVALID_UNSUBSCRIBE_TOKEN`.
|
|
|
|
**Verified by:**
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/webhooks/routes.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/webhooks/schemas.test.ts`,
|
|
`packages/api-stack/api/api-plugin-campaigns/src/routes/webhooks/build-routes.test.ts`
|
|
(20+ cases covering the three negative-event paths, idempotent retries,
|
|
token-decode failure modes, and registry-less fallback).
|
|
|
|
#### Scenario: Negative-event auto-suppression
|
|
|
|
- **GIVEN** a `POST /webhooks/delivery` with body
|
|
`{ messageId: "m1", eventType: "unsubscribed", contactId: "u1", channel: "email" }`
|
|
- **WHEN** the request completes
|
|
- **THEN** the response SHALL be HTTP 200 with `data.suppressed === true`,
|
|
AND `campaignSuppressionStore.check("t", "email", "u1")` SHALL return a
|
|
non-null entry with `reason === "unsubscribe"`.
|
|
|
|
### Requirement: Plugin onInit wiring (Chunk C)
|
|
|
|
The plugin's `onInit` SHALL resolve `app` and `db` from the host
|
|
`ServiceRegistry`, construct the SurrealDB-backed `CampaignStore`,
|
|
`CampaignSuppressionStore`, and `DeliveryEventStore` implementations,
|
|
register them on the registry plus the Hono `ContextVariableMap` via a
|
|
single mount-pattern middleware, and mount every route through
|
|
`definePluginRoutes` when an `openAPIRegistry` slot is available.
|
|
Missing `app` or `db` slots SHALL raise
|
|
`CAMPAIGNS_API.SERVICE_NOT_AVAILABLE`. A registered registry with
|
|
pre-existing routes under the configured prefix SHALL raise
|
|
`CAMPAIGNS_API.ROUTE_PREFIX_COLLISION`.
|
|
|
|
**Verified by:**
|
|
`packages/api-stack/api/api-plugin-campaigns/src/plugin/plugin.test.ts`
|
|
(18 cases covering happy-path onInit, both SERVICE_NOT_AVAILABLE
|
|
branches, registry warning fallback, ROUTE_PREFIX_COLLISION re-run,
|
|
custom-prefix routing, and idGenerator/clock default exercise) and
|
|
`packages/api-stack/api/api-plugin-campaigns/tests/integration/plugin-integration.test.ts`
|
|
(8 end-to-end cases against a real `OpenAPIHono` host with in-memory
|
|
repositories — no mocks).
|
|
|
|
#### Scenario: Missing db service
|
|
|
|
- **GIVEN** a host with `app` registered but no `db` slot
|
|
- **WHEN** the campaigns plugin's `onInit` runs
|
|
- **THEN** the call SHALL throw `CampaignsApiError` carrying
|
|
`CAMPAIGNS_API.SERVICE_NOT_AVAILABLE` with `context.missing === ["db"]`.
|
|
|
|
#### Scenario: Route-prefix collision
|
|
|
|
- **GIVEN** an `OpenAPIRegistry` already carrying routes under
|
|
`/campaigns`
|
|
- **WHEN** the campaigns plugin's `onInit` runs against that registry
|
|
- **THEN** the call SHALL throw `CampaignsApiError` carrying
|
|
`CAMPAIGNS_API.ROUTE_PREFIX_COLLISION`.
|