@codewithagents/openapi-server 1.9.0 → 1.10.0

package/README.md

@@ -216,7 +216,8 @@ See the [full configuration reference](https://openapi.codewithagents.de/openapi
   "input_openapi": "./spec/api.json",       // required: path to OpenAPI 3.x spec (JSON or YAML)
   "output": "./generated",                  // required: directory to write generated files
   "framework": "hono",                      // optional: router target (default: "none")
-  "input_schema": "./generated/schemas.ts"  // optional: Zod schema file for request validation
+  "input_schema": "./generated/schemas.ts", // optional: Zod schema file for request validation
+  "context_type": "RequestContext"          // optional: TypeScript type for per-request caller context
 }
 ```
 
@@ -226,6 +227,7 @@ See the [full configuration reference](https://openapi.codewithagents.de/openapi
 | `output` | Yes | n/a | Directory to write `service.ts` and `router.ts` |
 | `framework` | No | `"none"` | Router framework to generate: `"hono"`, `"express"`, `"fastify"`, or `"none"`. Use `"none"` to generate only `service.ts` |
 | `input_schema` | No | none | Path to user-owned Zod schema file. Enables server-side request validation (see below) |
+| `context_type` | No | none | TypeScript type name to thread through service methods as a final `ctx` argument. See below. |
 
 Use `--config <path>` to point at a config file in a different location:
 
@@ -315,6 +317,241 @@ fastify.register(async (instance) => { createRouter(instance, service) }, { pref
 
 The `"none"` path is always available and keeps the zero-footprint promise: the generated code has no runtime dependencies that you did not already choose.
 
+## Cookie parameter validation
+
+Operations that declare `in: cookie` parameters get the same Zod validation treatment as header and query params. The generator reads the cookie name and schema constraints (required, enum, minLength, maxLength, pattern) from the spec and emits a `_ckv` safeParse block in the generated route handler. Failures return `422 { error: 'Invalid request cookies', issues }`.
+
+Cookie names are case-sensitive (unlike HTTP headers, which are always lowercased before lookup). The exact name from the spec is used for both the Zod field key and the value lookup.
+
+Cookies are not forwarded to the service method signature. They are validated in the router layer only. Forwarding cookies to service methods is out of scope for the current release.
+
+**Per-framework plugin requirements:**
+
+| Framework | Required plugin / middleware | Cookie accessor |
+|---|---|---|
+| Fastify | `@fastify/cookie` registered before the router | `req.cookies['name']` |
+| Express | `cookie-parser` middleware applied before mounting the router | `req.cookies['name']` |
+| Hono | `hono/cookie` (imported automatically in the generated output) | `getCookie(c, 'name')` |
+
+**Fastify setup:**
+
+```ts
+import fastifyCookie from '@fastify/cookie'
+
+fastify.register(fastifyCookie)
+fastify.register(async (instance) => { createRouter(instance, service) }, { prefix: '/api' })
+```
+
+**Express setup:**
+
+```ts
+import cookieParser from 'cookie-parser'
+
+app.use(cookieParser())
+app.use('/api', createRouter(service))
+```
+
+**Hono setup:**
+
+No extra setup needed. The generator automatically adds `import { getCookie } from 'hono/cookie'` to the generated router when the spec declares cookie params. `hono/cookie` ships with Hono; no additional install is required.
+
+---
+
 ## Error handling and troubleshooting
 
-The generated router does not wrap service calls in `try/catch`. Errors propagate to the framework's own error handler. See [Error handling](https://openapi.codewithagents.de/openapi-server#error-handling) in the docs for per-framework error handler examples and [Troubleshooting](https://openapi.codewithagents.de/openapi-server#troubleshooting) for common issues such as missing Zod validation or `Cannot find module './models.js'`.
+The generated router wraps every service call in a `try/catch` block. The catch block handles two cases:
+
+- **`HttpError`** (exported from the generated `router.ts`): caught inline and mapped to its `.status` code. Use `new HttpError(404, 'Pet not found')` inside service methods to return structured HTTP error responses.
+- **All other errors**: re-thrown to the framework's own error handler (`setErrorHandler` in Fastify, error-handling middleware in Express, `app.onError` in Hono).
+
+This means custom error types that do NOT extend `HttpError` propagate to the framework layer, where you install a single error handler for logging, monitoring, and response shaping.
+
+**Example: custom error reaching Fastify's `setErrorHandler`**
+
+```ts
+// Your custom error class — does NOT extend HttpError
+class NotFoundError extends Error {
+  constructor(resource: string) {
+    super(`${resource} not found`)
+    this.name = 'NotFoundError'
+  }
+}
+
+// Service implementation throws NotFoundError
+export const petService: PetstoreService = {
+  async getPet(id) {
+    const pet = db.get(id)
+    if (!pet) throw new NotFoundError(`Pet ${id}`)
+    return pet
+  },
+  // ...
+}
+
+// Register a Fastify error handler ONCE at the app level.
+// The generated router re-throws non-HttpError errors, so they arrive here.
+fastify.setErrorHandler((err, request, reply) => {
+  if (err.name === 'NotFoundError') {
+    return reply.status(404).send({ error: err.message })
+  }
+  // Unknown errors become 500
+  fastify.log.error(err)
+  return reply.status(500).send({ error: 'Internal server error' })
+})
+
+fastify.register(async (instance) => { createRouter(instance, petService) }, { prefix: '/api' })
+```
+
+The same pattern applies to Express error middleware (`app.use((err, req, res, next) => { ... })`) and to Hono's `app.onError((err, c) => { ... })`.
+
+See [Error handling](https://openapi.codewithagents.de/openapi-server#error-handling) in the docs for per-framework error handler examples and [Troubleshooting](https://openapi.codewithagents.de/openapi-server#troubleshooting) for common issues such as missing Zod validation or `Cannot find module './models.js'`.
+
+---
+
+## Request-scoped context / caller principal (`context_type`)
+
+The `context_type` config option threads a typed caller context through every generated service method. Use it to pass an authentication principal, a tenant ID, or any per-request metadata without coupling service code to framework types.
+
+**Config:**
+
+```json
+{
+  "input_openapi": "./spec/api.json",
+  "output": "./generated",
+  "framework": "hono",
+  "context_type": "RequestContext"
+}
+```
+
+**What changes in generated `service.ts`:**
+
+```ts
+// Without context_type (default):
+export interface PetstoreService {
+  listPets(params?: { species?: string }): Promise<Pet[]>
+  getPet(id: string): Promise<Pet>
+}
+
+// With context_type: "RequestContext":
+export interface PetstoreService<Ctx = never> {
+  listPets(params?: { species?: string }, ctx: Ctx): Promise<Pet[]>
+  getPet(id: string, ctx: Ctx): Promise<Pet>
+}
+```
+
+The generic default `Ctx = never` keeps the interface usable when no context is needed: existing implementations that do not pass ctx continue to compile as long as the service is instantiated without a type argument.
+
+**What changes in generated `router.ts`:**
+
+The generated router passes the framework's native request/context object as the final argument to every service call:
+
+| Framework | ctx value passed |
+|---|---|
+| Hono | `c` (the Hono `Context` object) |
+| Express | `req` (the Express `Request` object) |
+| Fastify | `req` (the Fastify `FastifyRequest` object) |
+
+```ts
+// Generated Hono handler (with context_type: "RequestContext"):
+app.get('/pets', async (c) => {
+  try {
+    return c.json(await service.listPets(c))
+  } catch (err) { ... }
+})
+```
+
+**Implementing the service with context:**
+
+```ts
+import type { PetstoreService } from '../generated/service.js'
+import type { Context } from 'hono'
+
+// Define your request context type
+interface RequestContext {
+  userId: string
+  tenantId: string
+}
+
+// Extract context from the Hono Context object in a middleware
+const app = new Hono()
+app.use('*', async (c, next) => {
+  const userId = c.req.header('x-user-id') ?? ''
+  // Store on the Hono context so the generated router can pass it
+  c.set('userId', userId)
+  await next()
+})
+
+// Implement the service — ctx is whatever the router passed (here: the Hono Context)
+export const petService: PetstoreService<Context> = {
+  async listPets(params, ctx) {
+    const userId = ctx.get('userId')
+    return db.listPets({ userId, ...params })
+  },
+  async getPet(id, ctx) {
+    const userId = ctx.get('userId')
+    return db.getPet(id, userId)
+  },
+}
+```
+
+**Backward compatibility:** if `context_type` is not set in the config, the generated output is identical to previous versions. No changes to the interface shape, no extra arguments in service calls.
+
+---
+
+## Non-JSON request bodies (Fastify)
+
+Fastify 5 natively parses only `application/json` and `text/plain` request bodies. For other content types you must register the appropriate plugin before the generated router.
+
+### application/x-www-form-urlencoded
+
+Install and register [`@fastify/formbody`](https://github.com/fastify/fastify-formbody):
+
+```bash
+pnpm add @fastify/formbody
+```
+
+```ts
+import fastifyFormbody from '@fastify/formbody'
+
+fastify.register(fastifyFormbody)
+fastify.register(async (instance) => { createRouter(instance, service) }, { prefix: '/api' })
+```
+
+Without this plugin, `req.body` is `undefined` for form-urlencoded requests and the handler receives no body.
+
+### multipart/form-data
+
+Install and register [`@fastify/multipart`](https://github.com/fastify/fastify-multipart) with `attachFieldsToBody: true`:
+
+```bash
+pnpm add @fastify/multipart
+```
+
+```ts
+import fastifyMultipart from '@fastify/multipart'
+
+fastify.register(fastifyMultipart, { attachFieldsToBody: true })
+fastify.register(async (instance) => { createRouter(instance, service) }, { prefix: '/api' })
+```
+
+The `attachFieldsToBody` option is required. Without it, `@fastify/multipart` v10 exposes uploaded files only via async iterators (`request.parts()`), not via `req.body`. The generated router reads `req.body` and passes it to the service method, so `attachFieldsToBody: true` must be set.
+
+### application/octet-stream
+
+No extra plugin is needed. When your spec declares an `application/octet-stream` request body, the generator automatically emits an `addContentTypeParser` call inside `createRouter`:
+
+```ts
+app.addContentTypeParser('application/octet-stream', { parseAs: 'buffer' }, (req, body, done) => done(null, body))
+```
+
+`addContentTypeParser` is a core Fastify API with no additional dependencies. The parsed body is a `Buffer` and is forwarded directly to the service method.
+
+### 415 error-shape divergence
+
+When a request arrives with an unsupported content type and no parser is registered, the two frameworks return different shapes:
+
+| Framework | Status | Body shape |
+|---|---|---|
+| Hono | 415 | `{ error: 'Unsupported Media Type' }` |
+| Fastify | 415 | `{ statusCode: 415, code: 'FST_ERR_CTP_INVALID_MEDIA_TYPE', error: 'Unsupported Media Type', message: '...' }` |
+
+Hono uses the shared `{ error }` envelope from the generated router. Fastify uses its own framework-level 415 envelope, which is emitted before the route handler runs. If you rely on a consistent error shape across frameworks, register the appropriate parser or add a Fastify `setErrorHandler` that normalises the response.