Initial Commit

openspec/specs/api-plugin-campaigns/spec.md

@@ -0,0 +1,298 @@
+# `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`.