first commit

docs/api-stack/api/api-plugin-campaigns/src/routes/suppression/build-routes.md

@@ -0,0 +1,61 @@
+# `build-routes` (suppression)
+
+## Purpose
+
+`buildSuppressionRoutes` aggregates the four `/suppression/*` plugin
+route entries in canonical order (list, check, create, delete). The
+plugin's `onInit` consumes the array verbatim, so the OpenAPI spec
+order is deterministic and tests can assert it as a contract. Keeping
+the aggregator in its own module (rather than collapsed into the
+`routes.ts` file) mirrors the layout used elsewhere in the
+`@suaveplan/*` plugin family — code-search "build-routes" always
+finds the canonical-order anchor.
+
+## Features
+
+- Returns 4 entries in the documented canonical order.
+- Pure — no I/O, no captured state, no configuration knobs.
+- Each entry is independently mountable on a bare `Hono` app for
+  testing.
+
+## Usage: Basic
+
+```ts
+import { buildSuppressionRoutes } from "@suaveplan/api-plugin-campaigns";
+
+for (const e of buildSuppressionRoutes()) {
+    app[e.route.method as "get" | "post" | "delete"](e.route.path, (c) =>
+        e.handler(c)
+    );
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    buildSuppressionRoutes,
+    definePluginRoutes,
+} from "@suaveplan/api-plugin-campaigns";
+
+const entries = buildSuppressionRoutes().map((e) => ({
+    ...e,
+    route: { ...e.route, path: `/api${e.route.path}` },
+}));
+definePluginRoutes(entries, { app, registry, pluginName: "campaigns" });
+```
+
+## API Reference
+
+- `buildSuppressionRoutes(): readonly PluginRouteEntry[]` — returns
+  the 4 entries in canonical order.
+
+## Implementation Notes
+
+The check endpoint sits at position 2 (between list and create)
+because cache-friendly `GET` reads precede writes in the canonical
+order — operator-facing OpenAPI consumers naturally scan the read
+surface first when assessing rate-limit and caching budgets. The
+delete endpoint is last so the OpenAPI consumer reading the spec
+top-down sees the destructive operation last and is prompted to
+consider authentication scope before mounting.