# `build-routes.ts`

## Purpose

Builds the 6 OpenAPI route entries the plugin mounts on the host Hono app: single-shot `POST /`, chunked-init `POST /initiate`, chunk append `PUT /{uploadId}/chunks/{chunkIndex}`, finalise `POST /{uploadId}/complete`, abort `DELETE /{uploadId}`, and status `GET /{uploadId}`. Each route uses `RouteBuilder` from `@suaveplan/api-openapi` so request/response schemas flow through end-to-end, keeping the served `/openapi.json` document accurate against the live wire surface.

## Features

- Six routes registered with typed request bodies, params, and responses.
- Single shared service handle (`FileUploadService`) wired into every handler, so the routes do not own any per-request state.
- Reuses the same `SingleShotResponseSchema` across `POST /` and `POST /{uploadId}/complete` so clients have a uniform success shape regardless of which upload mode they used.

## Usage: Basic

```ts
import { buildUploadRoutes } from "@suaveplan/api-plugin-file-upload/routes/routes";
import { definePluginRoutes } from "@suaveplan/api-openapi";

definePluginRoutes(buildUploadRoutes(service), {
    app,
    registry: openAPIRegistry,
    pluginName: "file-upload",
});
```

## Usage: Advanced

```ts
import { buildUploadRoutes } from "@suaveplan/api-plugin-file-upload";

const entries = buildUploadRoutes(service);
for (const entry of entries) {
    console.log(entry.route.method, entry.route.path);
}
// → post /
// → post /initiate
// → put /{uploadId}/chunks/{chunkIndex}
// → post /{uploadId}/complete
// → delete /{uploadId}
// → get /{uploadId}
```

## API Reference

- `buildUploadRoutes(service: FileUploadService): PluginRouteEntry[]` — returns the 6 ready-to-mount entries.

## Implementation Notes

- The paths use OpenAPI `{name}` placeholders (not Hono's `:name`) because `RouteBuilder` emits OpenAPI 3.1 path templates. `@hono/zod-openapi` translates back to Hono's parameter syntax at registration.
- The single-shot route uses `POST /` — Hono mounts it under `basePath`, so the final URL is `POST {basePath}` (default `POST /uploads`).
- All routes return JSON. Multipart parsing for the single-shot path happens INSIDE the handler so the route table stays declarative.