# `routes/private-routes.ts`

## Purpose

Builds the authenticated Hono route tree for site CRUD and domain management. The factory is intentionally auth-agnostic — the suaveplan convention is that the host application composes auth middleware (`requireAuth()` from `@suaveplan/api-plugin-auth` or any equivalent) at the prefix where this router is mounted. Decoupling auth from the route factory keeps the package usable by any consumer (e.g. a future GraphQL gateway, an admin CLI) without forcing a hard dependency on a specific auth plugin.

## Features

- `POST /sites` — create.
- `PATCH /sites/{id}` — update name / settings.
- `POST /sites/{id}/domains` — add domain.
- `DELETE /sites/{id}/domains` — remove domain.
- OpenAPI schemas embedded inline via `@hono/zod-openapi` so the generated spec is the contract.
- Errors propagate as `SiteError` (caught and rendered by the host's global error middleware).

## Usage: Basic

```ts
import { createPrivateSiteRoutes } from "@suaveplan/api-plugin-site/routes/private-routes";

const privateRouter = createPrivateSiteRoutes({ siteService });
app.use("/api/v1", requireAuth());
app.route("/api/v1", privateRouter);
```

## Usage: Advanced

```ts
// Layer additional rate-limit + audit middleware on top.
const privateRouter = createPrivateSiteRoutes({ siteService });
app.use("/admin", requireAuth(), rateLimit({ key: "site-mutations" }));
app.route("/admin", privateRouter);
```

## API Reference

- `interface PrivateSiteRoutesDeps` — `siteService`.
- `createPrivateSiteRoutes(deps: PrivateSiteRoutesDeps): OpenAPIHono`.

## Recommended middleware

Write routes benefit most from layered rate-limit + audit middleware. The site plugin ships the `MIDDLEWARE_RECOMMENDATIONS` constant (see `src/integration/middleware-recommendations.md`) describing the recommended ceiling and audit category for this group:

- **Rate-limit**: `30 req / 60s` on the `/sites/*` path pattern (`private:write` group). Writes are rare per tenant and warrant the tightest ceiling; this protects the database from runaway clients without inconveniencing legitimate operators.
- **Audit category**: `data.mutation`. Every successful or failed write produces one `AuditEvent` in the host's configured `AuditStorageAdapter`. Combine with `enableChainIntegrity: true` for a tamper-evident trail.

The recommended layering order — audit OUTERMOST, rate-limit MIDDLE, site routes INNERMOST — is documented end-to-end in `docs/middleware-integration.md` and proven by `src/integration/middleware-composition.integration.test.ts`. The site plugin does not bind either middleware itself; composition stays in the host via the Hono `app.use(prefix, middleware)` pattern.

## Implementation Notes

- The factory accepts a single deps object so future additions (audit, event bus) stay non-breaking.
- All bodies are Zod-validated via `@hono/zod-openapi` — invalid input is rejected before reaching the service.
- The "remove domain" endpoint uses a body (not a path segment) so callers can submit the canonical-cased domain string and so the operation can be batched in future without an additional route shape.