# @suaveplan/api-router — contract package for the Suaveplan API plugin system. Defines the abstract Router interface (verb methods + use + mount + match), Request / Response host-side shapes, Zod-validated RouteOptions schema, Middleware composition helpers with insertion-point guard, RouteMatch shape, BlueGreenSlot interface for hot-reload, the frozen ROUTER_CODES registry, and the runRouterConformance harness every concrete adapter must pass. Stage-1 contract package for the Suaveplan API plugin system. This package defines the abstract `Router` interface, the host-side `Request` / `Response` shapes, the Zod-validated `RouteOptions` schema, the `Middleware` composition contract with insertion-point guard, the `RouteMatch` shape, the `BlueGreenSlot` interface backing hot reload, the frozen `ROUTER_CODES` registry, and the `runRouterConformance` harness every concrete adapter must pass. The reference in-memory `Router` and `InMemoryBlueGreenSlot` implementations ship here so the conformance harness is self-checking and Stage-1 consumers have a working router before any concrete adapter lands. ## Documentation tree - [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the single source of truth for every failure class this package surfaces. It exports the fr… - [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the single source of truth for every failure class this package surfaces. It exports the fr… - [middleware](./src/middleware/middleware.md) — The `middleware` module defines the onion-model `Middleware` contract and the `composeMiddleware` builder. Every adapte… - [insertion-point](./src/middleware/insertion-point.md) — The `insertion-point` module enforces the security invariant from design doc §6: plugin-supplied middleware is allowed… - [middleware](./src/middleware/middleware.md) — The `middleware` module defines the onion-model `Middleware` contract and the `composeMiddleware` builder. Every adapte… - [request](./src/request/request.md) — The `request` module defines the host-side `RouterRequest` shape — the post-parse, post-validation view that route hand… - [request](./src/request/request.md) — The `request` module defines the host-side `RouterRequest` shape — the post-parse, post-validation view that route hand… - [response](./src/response/response.md) — The `response` module provides the host-side `RouterResponse` shape and a fluent `ResponseBuilder` that adapters serial… - [response](./src/response/response.md) — The `response` module provides the host-side `RouterResponse` shape and a fluent `ResponseBuilder` that adapters serial… - [route-match](./src/route-match/route-match.md) — The `route-match` module defines `RouteMatch`, the shape every concrete adapter yields after resolving an incoming `(me… - [route-match](./src/route-match/route-match.md) — The `route-match` module defines `RouteMatch`, the shape every concrete adapter yields after resolving an incoming `(me… - [route-options](./src/route-options/route-options.md) — The `route-options` module is the Zod-validated boundary for every per-route configuration block. It widens the minimal… - [route-options](./src/route-options/route-options.md) — The `route-options` module is the Zod-validated boundary for every per-route configuration block. It widens the minimal… - [router](./src/router/router.md) — The `router` module defines the abstract `Router` — the verb-method surface (`get` / `post` / `put` / `patch` / `delete… - [router](./src/router/router.md) — The `router` module defines the abstract `Router` — the verb-method surface (`get` / `post` / `put` / `patch` / `delete… - [slot](./src/slot/slot.md) — The `slot` module defines `BlueGreenSlot` — the per-plugin atomic mount point that backs hot-reload. It exposes three p… - [slot](./src/slot/slot.md) — The `slot` module defines `BlueGreenSlot` — the per-plugin atomic mount point that backs hot-reload. It exposes three p… - [testing](./src/testing/conformance.md) — The `testing/conformance` module exports `runRouterConformance(factory)` — the canonical conformance harness every conc… - [pipeline-router-conformance](./src/testing/pipeline-router-conformance/pipeline-router-conformance.md) — `runPipelineRouterConformance(factory)` is the canonical contract suite every concrete `PipelineRouter` adapter MUST pa… - [pipeline-router-conformance](./src/testing/pipeline-router-conformance/pipeline-router-conformance.md) — `runPipelineRouterConformance(factory)` is the canonical contract suite every concrete `PipelineRouter` adapter MUST pa… - [conformance](./src/testing/conformance.md) — The `testing/conformance` module exports `runRouterConformance(factory)` — the canonical conformance harness every conc… ## Status - Version: `0.1.0` - Stage: 1 (Contracts) — see umbrella design. - Dependents: none yet (host wires this in). ## Install ```bash bun add @suaveplan/api-router ``` ## Modules - [`router`](./src/router/router.md) — abstract `Router` + reference in-memory implementation. - [`request`](./src/request/request.md) — host-side `RouterRequest` + `MapHeaders`. - [`response`](./src/response/response.md) — `RouterResponse` + fluent builder. - [`route-options`](./src/route-options/route-options.md) — Zod-validated `RouteOptions`. - [`middleware`](./src/middleware/middleware.md) — onion-model `Middleware` + `composeMiddleware`. - [`middleware/insertion-point`](./src/middleware/insertion-point.md) — pipeline-step guard. - [`route-match`](./src/route-match/route-match.md) — `RouteMatch` shape + factory. - [`slot`](./src/slot/slot.md) — `BlueGreenSlot` interface + in-memory reference impl. - [`error-codes`](./src/error-codes/error-codes.md) — `ROUTER_CODES` + `RouterError`. - [`testing/conformance`](./src/testing/conformance.md) — `runRouterConformance` adapter harness. ## Error codes The five frozen codes (every one thrown by a production path): - `ROUTER.ROUTE_COLLISION` - `ROUTER.INVALID_PREFIX` - `ROUTER.MIDDLEWARE_INSERTION_DENIED` - `ROUTER.SLOT_FLIP_FAILED` - `ROUTER.SLOT_DISPOSE_TIMEOUT` ## Subpath exports Every module has its own subpath export so consumers tree-shake to exactly what they import: ```ts import { Router } from "@suaveplan/api-router/router"; import { composeMiddleware } from "@suaveplan/api-router/middleware"; import { parseRouteOptions } from "@suaveplan/api-router/route-options"; import { runRouterConformance } from "@suaveplan/api-router/testing"; ``` ## Verification - `bunx turbo lint typecheck test --filter=@suaveplan/api-router` — green. - `bunx turbo test:coverage --filter=@suaveplan/api-router` — 100/100/100/100. - `bunx turbo build --filter=@suaveplan/api-router` — green. ## License MIT