# Tasks — add-api-plugin-webhook

> Every checkbox MUST reflect work actually done in this change. No retroactive ticking.

## 1. Spec authoring

- [x] 1.1 Read `../suaveplan/enterprise/api-plugin-webhook.md` end-to-end
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
- [x] 1.3 Draft `proposal.md` from `openspec/templates/proposal.md`
- [x] 1.4 Fill `## Source mapping` — every requirement cites enterprise audit line + justified additions
- [x] 1.5 Draft `specs/api-plugin-webhook/spec.md` from `openspec/templates/spec-delta.md`
- [x] 1.6 Every requirement carries a `**Verified by:**` line at authoring time

## 2. Implementation

- [x] 2.1 `src/error-codes/error-codes.{ts,test.ts,md,index.ts}` — 10 `WEBHOOK_*` codes + `WebhookError`
- [x] 2.2 `src/types/types.{ts,md,index.ts}` — `WebhookEndpoint`, `CreateEndpointInput`, `UpdateEndpointInput`, `WebhookPluginOptions`, `WebhookPluginConfig`
- [x] 2.3 `src/schemas/endpoint.{ts,test.ts,md,index.ts}` — `WebhookEndpointSchema`, `CreateEndpointInputSchema`, `UpdateEndpointInputSchema`
- [x] 2.4 `src/schemas/options.{ts,test.ts,md,index.ts}` — `WebhookPluginOptionsSchema`
- [x] 2.5 `src/schemas/routes/*.{ts,test.ts,md}` + `index.ts` — per-route schemas (`list`, `create`, `read`, `update`, `delete`, `test`)
- [x] 2.6 `src/otel/instruments.{ts,test.ts,md,index.ts}` — counters + histograms, reset for tests
- [x] 2.7 `src/store/endpoint-store.{ts,md,index.ts}` — `EndpointStore` interface
- [x] 2.8 `src/store/memory.{ts,test.ts,md}` — `MemoryEndpointStore`
- [x] 2.9 `src/dead-letter/dead-letter.{ts,md,index.ts}` — `DeadLetterSink` interface + `DeadLetterEntry`
- [x] 2.10 `src/dead-letter/memory.{ts,test.ts,md}` — `MemoryDeadLetterSink`
- [x] 2.11 `src/services/webhook-service.{ts,test.ts,md,index.ts}` — `WebhookService` impl wrapping `@suaveplan/webhook-client`
- [x] 2.12 `src/services/registry-augmentation.ts` — `ServiceRegistry` augmentation
- [x] 2.13 `src/routes/build-routes.{ts,test.ts,md,index.ts}` — `buildWebhookRoutes(service, opts)` returning `PluginRouteEntry[]`
- [x] 2.14 `src/plugin/plugin.{ts,test.ts,md,index.ts}` — `createWebhookPlugin(options)` factory + 5-step `onInit` lifecycle
- [x] 2.15 `src/api-plugin-webhook.spec-conformance.test.ts` — every `WEBHOOK_*` code thrown from a production path; `expectTypeOf` on `WebhookService`, registry augmentation
- [x] 2.16 `src/index.ts` — explicit named re-exports only

## 3. Tests

- [x] 3.1 Co-located `*.test.ts` per spec scenario via `@suaveplan/testing/runner`
- [x] 3.2 `tests/integration/delivery.test.ts` — real Hono receiver on random port: register → send → receive; assert HMAC sig + canonical headers + payload
- [x] 3.3 `tests/integration/retry.test.ts` — receiver returns 500 twice then 200; delivery succeeds, `attempts.length === 3`
- [x] 3.4 `tests/integration/dead-letter.test.ts` — receiver always returns 500; after `maxAttempts` send rejects with `DELIVERY_EXHAUSTED` and dead-letter sink contains the entry
- [x] 3.5 `tests/integration/full-boot.test.ts` — real `PluginRegistry` + real Hono app + real receiver; CRUD via routes then send via service
- [x] 3.6 `tests/dep-graph.test.ts` — pins 14 subpath exports + sibling `.md` per impl file
- [x] 3.7 All `it(...)` carry `{ timeout: 5000 }` (30000 for integration)
- [x] 3.8 Zero `vi.mock`, zero direct `from "vitest" | "bun:test"` imports

## 4. Documentation

- [x] 4.1 Sibling `.md` (≥200 words, basic + advanced examples, API reference) per impl file
- [x] 4.2 `README.md` — quick-start: `defineApp().use(createWebhookPlugin({ ... }))`; CRUD via routes; service-side `send()` recipes; `EndpointStore` / `DeadLetterSink` extension recipes; OTel + idempotency notes

## 5. Pre-archive verification (the 5 gates)

- [x] 5.1 `cd /home/paul/web/genesis && bun run check` — Biome 0/0/0 across the monorepo
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-webhook --force`
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-plugin-webhook` — 100/100/100/100
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-plugin-webhook` — exit 0
- [x] 5.5 `bunx turbo build --filter=@suaveplan/api-plugin-webhook --force`
- [x] 5.6 `bun scripts/lint/check-test-runner-imports.ts`

## 6. Pre-archive 9-row checklist

- [x] 6.1 Generics threaded; `expectTypeOf` assertions on `WebhookService` / `EndpointStore` / `ContextVariableMap`
- [x] 6.2 Zod schemas wired at every route + factory boundary
- [x] 6.3 Every `WEBHOOK_*` error code thrown by at least one production path (asserted by `api-plugin-webhook.spec-conformance.test.ts`)
- [x] 6.4 Strict-mode behaviors tested (invalid input rejected; ZodError surfaced as `cause`)
- [x] 6.5 OTel counters + histograms emitted from production paths and asserted via real in-memory `MeterProvider`
- [x] 6.6 Per-delivery in-flight dedup tested (concurrent `send()` with same key resolves to one delivery)
- [x] 6.7 No retroactive tick — every box above reflects work done in this change
- [x] 6.8 No `export *` in any feature barrel
- [x] 6.9 No direct `vitest` / `bun:test` imports in `src/` or `tests/`

## 7. Archive

- [x] 7.1 Fold spec delta into `openspec/specs/api-plugin-webhook/spec.md`
- [x] 7.2 Move `openspec/changes/add-api-plugin-webhook/` → `openspec/archive/2026-05-18-add-api-plugin-webhook/`
- [x] 7.3 DO NOT touch `MANIFEST.md` / `STATUS.md` (per orchestrator instruction)