@mpen/routekit 0.1.5 → 0.1.6

package/README.md

@@ -429,6 +429,127 @@ Available Valibot APIs:
 - `valibotSchemaMiddleware(options)`
 - `defineValibotMiddleware(options)`
 
+## Problem Responses
+
+Routekit includes first-class support for standard problem responses inspired by RFC 7807 (Problem Details), with practical adjustments optimized for modern TypeScript and API clients (such as distinct `success: boolean` discriminators and clear nested `error` code/message structures). Using standard problem envelopes keeps error responses predictable, typed, and structured across your entire API.
+
+### Response Helpers
+
+Import standard response helpers from `@mpen/routekit/response/problem`:
+
+```ts
+import { HttpStatus } from '@mpen/http'
+import {
+    ok,
+    created,
+    problem,
+    badRequest,
+    unauthenticated,
+    permissionDenied,
+    notFound,
+    conflict,
+    sessionExpired,
+    rateLimited,
+} from '@mpen/routekit/response/problem'
+
+// 200 OK standard success envelope
+// Returns { success: true, data: { ... } }
+router.get('/users/:id', () => ok({ id: 'user_123' }))
+
+// 201 Created standard success envelope
+// Returns { success: true, data: { ... } }
+router.post('/users', () => created({ id: 'user_123' }))
+
+// 404 Not Found problem details envelope
+// Returns { success: false, error: { code: 'not_found', message: 'User not found' } }
+router.get('/users/:id', ({ path }) => {
+    const user = findUser(path.id)
+    if (!user) {
+        return notFound('User not found')
+    }
+    return ok(user)
+})
+
+// Custom problem envelope
+// Returns { success: false, error: { code: 'out_of_stock', message: 'Item is sold out', title: 'Sold Out' } }
+router.post('/items/:id/buy', () => {
+    return problem({
+        status: HttpStatus.CONFLICT,
+        code: 'out_of_stock',
+        message: 'Item is sold out',
+        title: 'Sold Out',
+    })
+})
+```
+
+All standard problem helpers (`badRequest`, `unauthenticated`, `notFound`, etc.) accept a human-readable `message` string as the first argument, or a detailed options object with custom headers and error code overrides.
+
+### Router-level Errors
+
+You can automatically map default router-level failures (such as `404 Not Found` for unmatched paths, `405 Method Not Allowed`, `415 Unsupported Media Type`, and uncaught server errors) to standard problem envelopes by installing the `problemRootErrors()` extension:
+
+```ts
+import { Router } from '@mpen/routekit'
+import { problemRootErrors } from '@mpen/routekit/response/problem'
+
+const router = new Router().install(problemRootErrors())
+```
+
+### Valibot Integration
+
+Valibot helpers under `@mpen/routekit/response/problem/valibot` let you define schema boundaries and auto-validate endpoints using standard problem formats.
+
+```ts
+import { HttpStatus } from '@mpen/http'
+import { ok } from '@mpen/routekit/response/problem'
+import {
+    createValibotRouteBuilder,
+    okSchema,
+    problemSchema,
+} from '@mpen/routekit/response/problem/valibot'
+import * as v from 'valibot'
+
+// Create a route builder pre-configured to handle request validation errors.
+// It automatically responds with validation-failed problem envelopes on 400 or 422 errors.
+const route = createValibotRouteBuilder()
+
+router.post(
+    '/books',
+    route({
+        name: 'books.create',
+        schema: {
+            request: {
+                body: v.object({
+                    title: v.string(),
+                    author: v.string(),
+                }),
+            },
+            response: {
+                body: {
+                    [HttpStatus.OK]: okSchema(
+                        v.object({
+                            id: v.string(),
+                            title: v.string(),
+                        }),
+                    ),
+                    [HttpStatus.UNPROCESSABLE_ENTITY]: problemSchema({
+                        code: v.literal('todo_limit_exceeded'),
+                    }),
+                },
+            },
+        },
+        handler: ({ body }) => {
+            return ok({ id: '123', title: body.title })
+        },
+    }),
+)
+```
+
+By default, the route builder created by `createValibotRouteBuilder()` uses `problemValidationErrorHandler` to format query, path, and body validation failures:
+
+- Path and query parameters validation failures return `400 Bad Request` with `validation_failed:path` or `validation_failed:query` code.
+- Request body validation failures return `422 Unprocessable Content` with `validation_failed:body` code and a list of structured `issues` indicating precisely where the failure occurred.
+
 ## OpenAPI
 
 The `openapi()` handler reflects the active router's registered routes and schema metadata.
@@ -453,21 +574,53 @@ tags, security, and custom responses can be supplied beside the handler.
 
 ## Generated API Clients
 
-`routekit-gen-api-client` loads a router module, reads `router.getRoutes()`, and writes a
-typed client from each route's name, method, path, and JSON Schema metadata.
+Expose typed endpoints to your frontend or consumer clients by generating a fully typed API client. The Routekit CLI loads your server's router module, reads `router.getRoutes()`, and outputs a strongly typed client mapping each route's name, method, path, and JSON Schema metadata.
 
 ```bash
-bun run routekit-gen-api-client ./src/server/router.ts -o ./src/client/api-client.gen.ts -p
+$ bunx @mpen/routekit --help
+Usage: bun run packages/routekit/src/bin/gen-api-client.ts <router-file> [options]
+
+Generate a typed API client from a routekit router module.
+
+Arguments:
+  router-file                 Router module that exports a router with getRoutes()
+
+Options:
+  -o, --output <file>         File to write. Prints to stdout when omitted.
+  -w, --write                 Write to <router-file>.gen.ts beside the router file.
+  -p, --pretty                Format written output with Prettier.
+  -f, --format <format>       Output format: rk-api-client or ts-query-rk-problem. Defaults to rk-api-client.
+  --client-name <Name>        Generated client class name. Defaults to ApiClient.
+  --import-type <Type:module> Import a type used by generated schemas. Can be repeated.
+  --response-type <Type>      Generic response wrapper type. Defaults to ApiResponsePromise.
+  --help                      Show this help message.
 ```
 
-The router module must export a router instance as `default`, `router`, or another named
-export with a `getRoutes()` method.
+### Options Overview
+
+- `<router-file>`: Path to the router module file. The module must export a Routekit `Router` instance as `default`, `router`, or another named export with a `getRoutes()` method.
+- `-o, --output <file>`: File path to write. Prints to stdout when omitted.
+- `-w, --write`: A convenient shortcut to write the generated code directly to `<router-file>.gen.ts` beside the router module.
+- `-p, --pretty`: Automatically format the output using Prettier (requires Prettier to be installed).
+- `-f, --format <format>`: Choice of output generator format:
+    - `rk-api-client` (default): Generates a nested, class-based HTTP client mapping properties to URL paths.
+    - `ts-query-rk-problem`: Generates TanStack Query integration options (`queryOptions`, `mutationOptions`) tailored for APIs using the standard `@mpen/routekit/response/problem` envelopes.
 
-Generated clients use `@mpen/routekit/client`:
+---
+
+### Format: `rk-api-client` (Default)
+
+This format generates a nested, typed class client:
+
+```bash
+bunx @mpen/routekit ./src/server/router.ts -w -p
+```
+
+Usage:
 
 ```ts
 import { FetchTransport } from '@mpen/routekit/client'
-import { ApiClient } from './api-client.gen'
+import { ApiClient } from './router.gen'
 
 const client = new ApiClient(
     new FetchTransport({
@@ -476,10 +629,10 @@ const client = new ApiClient(
     }),
 )
 
+// Fully typed path parameters, query params, request body, and response union
 const response = await client.books.byId.post({
     path: 123,
     body: { title: 'Dune', author: 'Frank Herbert' },
-    headers: { 'content-type': 'application/json' },
 })
 
 if (response.ok) {
@@ -488,8 +641,7 @@ if (response.ok) {
 }
 ```
 
-Routes with multiple documented response statuses generate a response union narrowed by
-`response.status`:
+Routes with multiple documented response statuses generate a response union narrowed by `response.status`:
 
 ```ts
 const response = await client.widgets.byId.post(options)
@@ -500,9 +652,75 @@ if (response.status === 400) {
 }
 ```
 
-Use `--client-name <Name>` to change the generated class name, `--import-type
-<Type:module>` for external schema-generated types, and `--response-type <Type>` to use a
-custom generic response wrapper.
+---
+
+### Format: `ts-query-rk-problem` (TanStack Query + Problem Responses)
+
+This format generates TanStack Query integration helpers tailored for standard `@mpen/routekit/response/problem` envelopes. Specify `-f ts-query-rk-problem` when running client generation:
+
+```bash
+bunx @mpen/routekit ./src/server/router.ts -f ts-query-rk-problem -w -p
+```
+
+The generated file exports `createApiQueryHelpers()`, which generates a nested helper structure containing `queryOptions` and `mutationOptions`:
+
+```tsx
+import { useQuery, useMutation } from '@tanstack/react-query'
+import { FetchTransport } from '@mpen/routekit/client'
+import { createApiQueryHelpers, isRoutekitProblemError } from './router.gen'
+
+const transport = new FetchTransport({
+    baseUrl: 'https://api.example.com',
+    headers: () => ({ authorization: `Bearer ${token}` }),
+})
+
+const api = createApiQueryHelpers(transport)
+
+// 1. Querying data with automatically unwrapped successful payloads
+function BookDetails({ bookId }: { bookId: string }) {
+    const { data, error, isLoading } = useQuery(api.books.byId.get({ path: bookId }))
+
+    if (isLoading) return <div>Loading...</div>
+
+    // When a request returns a non-success problem envelope, error is typed as a RoutekitProblemError
+    if (error) {
+        if (isRoutekitProblemError(error)) {
+            return (
+                <div>
+                    Error: {error.body.error.message} ({error.body.error.code})
+                </div>
+            )
+        }
+        return <div>Unknown error occurred</div>
+    }
+
+    // Success data is automatically unwrapped from { success: true, data } envelope
+    return <h1>{data.title}</h1>
+}
+
+// 2. Mutations with typed variables and problem error handling
+function CreateBookForm() {
+    const mutation = useMutation(api.books.create.post())
+
+    const handleSubmit = (title: string, author: string) => {
+        mutation.mutate(
+            {
+                body: { title, author },
+            },
+            {
+                onError: (error) => {
+                    if (isRoutekitProblemError(error) && error.status === 422) {
+                        // Access structured validation issues
+                        console.log(error.body.issues)
+                    }
+                },
+            },
+        )
+    }
+
+    // ...
+}
+```
 
 ## Exports
 
@@ -511,6 +729,8 @@ custom generic response wrapper.
 - `@mpen/routekit/middleware` exports built-in middleware.
 - `@mpen/routekit/handlers` exports `openapi()`.
 - `@mpen/routekit/client` exports generated-client transports, response wrappers, body codecs, and URL/header helpers.
+- `@mpen/routekit/response/problem` exports RFC 7807 problem details response helpers.
+- `@mpen/routekit/response/problem/valibot` exports Valibot problem schemas and Valibot-specific problem route builders.
 
 ## Development
 

package/dist/{content-BuDOmhH_.mjs → content-vVRhLG82.mjs}

@@ -1,6 +1,6 @@
 import { a as response } from "./core-DbmQauwS.mjs";
 import { CommonContentTypes, CommonHeaders, HttpStatus } from "@mpen/http";
-//#region src/router/lib/format.ts
+//#region src/router/lib/fullwide.ts
 const FULL_WIDE_FORMAT = new Intl.NumberFormat("en-US", {
 	useGrouping: false,
 	maximumFractionDigits: 20

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { A as stream, B as parseMediaType, C as isChunkDirective, D as isStatusDirective, E as isRoutekitDirective, F as mediaRangeToContentType, I as mediaTypeMatches, L as normalizeMediaType, N as mediaRangeAccepts, O as isStreamDirective, P as mediaRangeQuality, R as parseAcceptHeader, S as headers, T as isHeadersDirective, _ as jsonResponseBodySerializer, a as createRoutekitRequest, b as chunk, c as jsonRequestBodyParser, d as urlEncodedRequestBodyParser, f as defineMiddleware, g as defaultResponseBodySerializers, h as createStartStream, i as UnsupportedRequestBodyMediaTypeError, j as mergeRouteSchemas, k as status, l as responseFromRequestBodyError, m as createAsyncStream, n as RequestBodyLengthMismatchError, o as defaultRequestBodyParsers, p as isDeclaredMiddleware, r as RequestBodyTooLargeError, s as formDataRequestBodyParser, t as RequestBodyError, u as textRequestBodyParser, v as jsonLinesFramer, w as isHeadDirective, x as head, y as sseFramer, z as parseContentType } from "./request-Dn0zc-xm.mjs";
 import { a as response, i as isRoutekitResponse, n as isResponseBodyInit, r as isRoutekitBody, t as body } from "./core-DbmQauwS.mjs";
-import { a as text } from "./content-BuDOmhH_.mjs";
+import { a as text } from "./content-vVRhLG82.mjs";
 import { CommonHeaders, HttpMethod, HttpStatus, StatusText } from "@mpen/http";
 import { ConsoleLogger } from "@mpen/logger";
 //#region src/router/lib/pathname.ts

package/dist/middleware.mjs

@@ -1,6 +1,6 @@
 import { C as isChunkDirective, O as isStreamDirective, R as parseAcceptHeader, S as headers, T as isHeadersDirective, f as defineMiddleware, n as RequestBodyLengthMismatchError, r as RequestBodyTooLargeError, w as isHeadDirective } from "./request-Dn0zc-xm.mjs";
 import { a as response, i as isRoutekitResponse, n as isResponseBodyInit } from "./core-DbmQauwS.mjs";
-import { a as text, t as empty } from "./content-BuDOmhH_.mjs";
+import { a as text, t as empty } from "./content-vVRhLG82.mjs";
 import { CommonHeaders, HttpMethod, HttpStatus } from "@mpen/http";
 import { LogLevel } from "@mpen/logger";
 //#region src/router/middleware/request-id-ctx.ts

package/dist/response/content.mjs

@@ -1,2 +1,2 @@
-import { a as text, i as html, n as noContent, r as redirect, t as empty } from "../content-BuDOmhH_.mjs";
+import { a as text, i as html, n as noContent, r as redirect, t as empty } from "../content-vVRhLG82.mjs";
 export { empty, html, noContent, redirect, text };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpen/routekit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Typed server-side routing utilities for Fetch-compatible runtimes.",
   "exports": {
     ".": "./dist/index.mjs",
@@ -81,9 +81,9 @@
     "access": "public"
   },
   "publishHash": {
-    "buildDate": "2026-05-30T18:01:34.790-07:00",
-    "hgChangesetId": "d5afc905fe8b+",
-    "sha256": "e03b7e8d2bb4a3997752353a73e339f2d8f6ffecf40164dcbeefe10e98d89a3d"
+    "buildDate": "2026-05-31T01:27:13.624-07:00",
+    "hgChangesetId": "3e4d8a8fe08b+",
+    "sha256": "bee8f482030f29b2fd923f2ce390284a1aa6a1c3f598fb74fdc1465e06ea7058"
   },
   "inlinedDependencies": {
     "@apidevtools/json-schema-ref-parser": "11.9.3",