`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

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

// 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.

3.1 KiB Raw Blame History

routes/private-routes.ts