@fresho/router 0.4.0 → 0.6.0

package/README.md

@@ -39,12 +39,13 @@ export default { fetch: api.handler() };
 
 ## Features
 
-- **Type-safe path params** — `$id` creates dynamic segments, typed via `route.ctx<>()`
+- **Type-safe path params** — `$id` creates dynamic segments whose names are inferred by handlers and clients
 - **Schema validation** — query and body validated at runtime, typed at compile time
 - **Property-based routing** — property names become URL segments
 - **Typed HTTP client** — call your API with full type safety
 - **Typed local client** — test handlers directly without HTTP
 - **OpenAPI generation** — auto-generate docs from your routes
+- **MCP server** — expose routes as tools for AI agents
 - **Middleware** — cors, auth, rate limiting, and more
 - **Streaming** — SSE and JSON lines helpers
 - **HTTP-compliant** — automatic HEAD support for GET routes
@@ -56,6 +57,16 @@ export default { fetch: api.handler() };
 npm install @fresho/router
 ```
 
+```bash
+bun add @fresho/router
+```
+
+## Runtime Support
+
+The full test suite runs in Node.js 22/24 and Bun 1.3.14. CI also deploys the built
+package to a local Cloudflare `workerd` runtime and verifies routing, validation,
+middleware, and streaming behavior.
+
 ## Path Convention
 
 Property names become URL path segments:
@@ -219,7 +230,7 @@ See **[Middleware Documentation](docs/middleware.md)** for detailed usage.
 For standalone auth utilities (JWT signing/verification, Basic auth, OAuth), import from `@fresho/router/auth`:
 
 ```typescript
-import { jwtSign, jwtVerify, parseBasicAuth } from "@fresho/router/auth";
+import { createJwks, jwtSign, jwtVerify, parseBasicAuth } from "@fresho/router/auth";
 
 // Sign a JWT
 const token = await jwtSign({ uid: "user-123" }, secret, { expiresIn: "1h" });
@@ -227,12 +238,20 @@ const token = await jwtSign({ uid: "user-123" }, secret, { expiresIn: "1h" });
 // Verify a JWT
 const payload = await jwtVerify(token, secret);
 
+// Verify a third-party OAuth/OIDC token against the provider's JWKS
+const jwks = createJwks("https://example.auth0.com/.well-known/jwks.json");
+const claims = await jwtVerify(accessToken, jwks, {
+	algorithms: ["RS256"],
+	issuer: "https://example.auth0.com/",
+	audience: "https://api.example.com",
+});
+
 // Parse Basic auth header
 const creds = parseBasicAuth(request.headers.get("Authorization"));
 ```
 
 Available utilities:
-- **JWT**: `jwtSign`, `jwtVerify`
+- **JWT**: `jwtSign`, `jwtVerify`, `createJwks` (HS*, RS*, PS*, ES256/384)
 - **Basic Auth**: `parseBasicAuth`, `encodeBasicAuth`, `extractBasicAuthToken`
 - **OAuth**: `encodeOAuthState`, `decodeOAuthState`, `exchangeCode`, `refreshAccessToken`, `revokeToken`, `buildAuthorizationUrl`, `OAUTH_PROVIDERS`
 
@@ -278,6 +297,26 @@ await client.users.$get();                    // GET /users
 await client.users.$post({ body: { name: "Bob" } }); // POST /users
 ```
 
+The `$id` segment determines the `id` key in the client's `path` option, so missing or misspelled
+parameter names are caught at compile time.
+
+### Routers Built by a Factory
+
+If your router is created inside a factory so its handlers can close over injected dependencies,
+derive the API type from the factory's return type. The type-only import keeps server code out of the
+client bundle:
+
+```typescript
+import { createHttpClient } from "@fresho/router";
+import type { createServer } from "./server";
+
+type Api = ReturnType<typeof createServer>["api"];
+
+const client = createHttpClient<Api>({
+	baseUrl: "https://api.example.com",
+});
+```
+
 ### HTTP Method Syntax
 
 HTTP methods are prefixed with `$` to distinguish them from path navigation:
@@ -297,7 +336,9 @@ This allows routes with path segments named after HTTP methods (e.g., `/api/get`
 
 ### Building URLs Without Fetching
 
-Use `$url` to derive a URL string from the typed routes without firing a request. It accepts the same `path`/`query` options as a real call, so path params stay type-checked:
+Use `$url` to derive a URL string from the typed routes without firing a request. It accepts the
+same `path`/`query` options as a real call, including the parameter names inferred from `$id`
+segments:
 
 ```typescript
 // Absolute URL when baseUrl is configured:
@@ -348,6 +389,52 @@ const docs = router({
 });
 ```
 
+## MCP Server
+
+Expose routes as [Model Context Protocol](https://modelcontextprotocol.io) tools, so agents can use the same API as your other clients. Requires the optional peer dependency `@modelcontextprotocol/sdk`:
+
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+```typescript
+import { router } from "@fresho/router";
+import { mcp } from "@fresho/router/mcp";
+
+const api = router({
+	users,
+	billing,
+	mcp: mcp({ users }, { name: "my-api", version: "1.0.0" }, bearerAuth({ verify })),
+});
+```
+
+`mcp()` requires endpoint middleware (usually auth). Pass `public: true` instead when the endpoint is open, or already guarded by middleware on its parent routers.
+
+- **Tools** — one per route, named from the method and path (`get_users`, `post_users`, `get_users_by_id`, ...) unless the route sets `operationId` (also used in OpenAPI). Descriptions come from `route.description`.
+- **Arguments** — flat: path params, query fields and body fields side by side (`{ id, text }`), as JSON Schema derived from the route's schemas. Names must be unique across the three; a clash throws when `mcp()` is called. `descriptions: { field: '...', 'address.city': '...' }` on a route documents fields for agents and OpenAPI. Array query params are left out, since the router can't parse them from query strings. Without a body schema, `post`/`put`/`patch` tools send any other arguments as the body.
+- **Annotations** — `get` tools are marked `readOnlyHint`, `delete` tools `destructiveHint` and `idempotentHint`, and `put` tools `idempotentHint`, so clients can decide when to ask for confirmation. Override per route with `mcp: { annotations: { ... } }`.
+- **Calls** — each tool call is dispatched as an HTTP request through the given routers with the caller's headers forwarded. Middleware on the MCP endpoint (passed to `mcp()` or on its parent routers) runs once per MCP request, and what it adds to the context (e.g. `c.user`) reaches handlers; middleware on the given routers and below runs on every call. Middleware on the given routers' *own* parents elsewhere in your app does **not** run, so guard the endpoint or the routers themselves. Responses become text content, plus `structuredContent` when the body is a JSON object; a non-2xx status sets `isError`, and streaming (SSE, NDJSON) responses are rejected.
+- **Safety** — requests with an `Origin` other than the endpoint's get 403 (as the MCP spec requires against DNS rebinding), so browser-hosted clients on other origins can't connect. Path parameters can't be `.` or `..`, and handler exceptions become a generic `Internal error`.
+- **Transport** — stateless Streamable HTTP with JSON responses; `GET` and `DELETE` return 405.
+- Pass a router to expose all of its routes, or a record of routers to mount them under their keys.
+
+### OAuth
+
+Put auth middleware on the endpoint so unauthenticated clients get an HTTP 401, and set `oauth` to advertise your authorization server (RFC 9728):
+
+```typescript
+const oauth = { authorizationServers: ["https://auth.example.com"], scopes: ["users:read"] };
+
+const app = router({
+	users,
+	mcp: mcp({ users }, { name: "my-api", version: "1.0.0", oauth }, jwtAuth({ ... })),
+	// Optional: metadata at the origin root, for clients that probe it before calling the endpoint.
+	".well-known": oauthProtectedResource(oauth),
+});
+```
+
+401s from the endpoint gain `WWW-Authenticate: Bearer resource_metadata="https://host/mcp/.well-known/oauth-protected-resource"`, and that URL serves the metadata without the endpoint's middleware (keep auth off the endpoint's parent routers, or the metadata is guarded too). `oauthProtectedResource` only handles single-segment endpoint paths such as `/mcp`. Validate that tokens were issued for this server (the `aud` claim), not just by your authorization server.
+
 ## Streaming
 
 ### Server-Sent Events
@@ -355,16 +442,36 @@ const docs = router({
 ```typescript
 import { sseResponse } from "@fresho/router";
 
+export interface ItemEvents {
+	message: { connected: boolean };
+	update: { count: number };
+	removed: { id: string };
+}
+
 events: router({
 	get: async () =>
-		sseResponse(async (send, close) => {
-			send({ data: "connected" });
+		sseResponse<ItemEvents>(async (send, close) => {
+			send({ data: { connected: true } });
 			send({ event: "update", data: { count: 1 } });
+			send({ event: "removed", data: { id: "item-1" } });
 			close();
 		}),
 });
 ```
 
+The event map checks event names and their corresponding payloads. The reserved `message` key types
+events that omit the `event` field. Export the map for consumers, or extract it from a typed client
+method:
+
+```typescript
+import type { SSEEventsOf } from "@fresho/router";
+
+type ClientEvents = SSEEventsOf<ReturnType<typeof client.events>>;
+```
+
+HTTP and local clients return streaming routes as raw `Response` objects instead of parsing their
+bodies as JSON, so callers can consume `response.body` as data arrives.
+
 ### JSON Lines
 
 ```typescript

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { a as VerifyJwtOptions, i as SignJwtOptions, n as JwtPayload, o as jwtSign, r as JwtSecret, s as jwtVerify, t as JwtAlgorithm } from "../jwt-DHM_nSwL.mjs";
+import { a as SignJwtOptions, c as jwtSign, i as JwtSecret, l as jwtVerify, n as JwtAlgorithm, o as VerifyJwtOptions, r as JwtPayload, s as createJwks, t as Jwks } from "../jwt-B-Fqwu4E.mjs";
 
 //#region src/auth/basic.d.ts
 
@@ -323,5 +323,5 @@ interface AuthorizationUrlOptions {
  */
 declare function buildAuthorizationUrl(options: AuthorizationUrlOptions): string;
 //#endregion
-export { type AuthorizationUrlOptions, type BasicCredentials, type ExchangeCodeOptions, type JwtAlgorithm, type JwtPayload, type JwtSecret, OAUTH_PROVIDERS, type OAuthProvider, type OAuthTokenResponse, type RevokeTokenOptions, type SignJwtOptions, type TokenAuthMethod, type VerifyJwtOptions, buildAuthorizationUrl, decodeOAuthState, encodeBasicAuth, encodeOAuthState, exchangeCode, extractBasicAuthToken, jwtSign, jwtVerify, parseBasicAuth, refreshAccessToken, revokeToken };
+export { type AuthorizationUrlOptions, type BasicCredentials, type ExchangeCodeOptions, type Jwks, type JwtAlgorithm, type JwtPayload, type JwtSecret, OAUTH_PROVIDERS, type OAuthProvider, type OAuthTokenResponse, type RevokeTokenOptions, type SignJwtOptions, type TokenAuthMethod, type VerifyJwtOptions, buildAuthorizationUrl, createJwks, decodeOAuthState, encodeBasicAuth, encodeOAuthState, exchangeCode, extractBasicAuthToken, jwtSign, jwtVerify, parseBasicAuth, refreshAccessToken, revokeToken };
 //# sourceMappingURL=index.d.mts.map

package/dist/auth/index.mjs

@@ -1,4 +1,4 @@
-import { a as parseBasicAuth, i as extractBasicAuthToken, n as jwtVerify, r as encodeBasicAuth, t as jwtSign } from "../jwt-Dab9kOC2.mjs";
+import { a as extractBasicAuthToken, i as encodeBasicAuth, n as jwtSign, o as parseBasicAuth, r as jwtVerify, t as createJwks } from "../jwt-ikNuUBcp.mjs";
 
 //#region src/auth/oauth.ts
 /** Common OAuth 2.0 providers with their endpoints. */
@@ -275,5 +275,5 @@ function buildAuthorizationUrl(options) {
 }
 
 //#endregion
-export { OAUTH_PROVIDERS, buildAuthorizationUrl, decodeOAuthState, encodeBasicAuth, encodeOAuthState, exchangeCode, extractBasicAuthToken, jwtSign, jwtVerify, parseBasicAuth, refreshAccessToken, revokeToken };
+export { OAUTH_PROVIDERS, buildAuthorizationUrl, createJwks, decodeOAuthState, encodeBasicAuth, encodeOAuthState, exchangeCode, extractBasicAuthToken, jwtSign, jwtVerify, parseBasicAuth, refreshAccessToken, revokeToken };
 //# sourceMappingURL=index.mjs.map