@schemavaults/openapi-operations 0.1.9 → 0.3.0

package/README.md

@@ -80,6 +80,27 @@ export const health = defineOperation({
 `defineOperationGroup({ pathPrefix, tags, operations })` applies a shared prefix and tags.
 Throw `new OperationError(status, { error, message })` from a handler to short-circuit.
 
+Schemas built by OTHER packages (e.g. `@schemavaults/auth-common`) may have been constructed
+before this package installed the `.openapi()` extension (zod v4 copies prototype methods onto
+each instance at construction time), in which case `schema.openapi(...)` throws at module load
+depending on import order. Use `withOpenApi(schema, refId?, metadata)` for them:
+
+```ts
+import { withOpenApi } from "@schemavaults/openapi-operations";
+export const Organization = withOpenApi(organizationDefinitionSchema, "Organization", { description: "..." });
+```
+
+Request bodies take two extra flags:
+
+- `lenientContentType: true` also parses bodies labelled `text/plain` (or carrying no
+  `Content-Type` at all) as the declared media type. Browsers send
+  `text/plain;charset=UTF-8` for `fetch(url, { body: JSON.stringify(x) })` without an
+  explicit header, so JSON endpoints with such callers need it.
+- `documentOnly: true` describes the body in the OpenAPI document but leaves the
+  request untouched: `ctx.body` is `undefined` and the handler reads `ctx.request`
+  itself. For endpoints whose parsing / error format is mandated by a protocol (the
+  OAuth 2.0 token endpoint's `{ error, error_description }`, ...).
+
 ### Auth schemes
 
 An `AuthSchemeDefinition` is a named OpenAPI security scheme plus docs metadata. Built-ins:
@@ -118,10 +139,14 @@ import { createOperationsApp, toNextRouteHandlers } from "@schemavaults/openapi-
 
 const app = createOperationsApp<{ dbh: Kysely<AuthDatabase> }, UserData>({
   operations: [getApp, health],
+  // Built per request BEFORE credentials are resolved (keep it cheap, open
+  // expensive resources lazily); released by disposeContext afterwards.
   context: async () => ({ dbh: await getDbh() }),
+  disposeContext: async ({ dbh }) => dbh.destroy(),
   authResolvers: {
-    // keyed by scheme name; return null when no credential for that scheme is present
-    "schemavaults-access-token": async (c) => {
+    // keyed by scheme name; return null when no credential for that scheme is
+    // present. The third argument is the per-request context.
+    "schemavaults-access-token": async (c, _scheme, { dbh }) => {
       const token = c.req.header("authorization")?.replace(/^Bearer /, "");
       if (!token) return null;
       const user = await verifyAccessToken(token); // throw OperationError(401, ...) if invalid
@@ -137,6 +162,8 @@ const app = createOperationsApp<{ dbh: Kysely<AuthDatabase> }, UserData>({
   // Served at GET /openapi.json. Pass a function to build it per request,
   // e.g. to set `servers` from the incoming Host / X-Forwarded-* headers.
   openapi: { document: openApiDocument },
+  // Unexpected failures: log / persist them before the generic 500 goes out.
+  onError: (error, c, { operation, context }) => reportException(error, operation.operationId),
 });
 
 // app/api/[[...route]]/route.ts
@@ -147,6 +174,47 @@ export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextRouteHandl
 export default toVercelHandler(app);
 ```
 
+### One route file per operation
+
+A catch-all is not required. To give every operation its own Next.js `route.ts`
+(or Vercel function file) while still serving one OpenAPI document that lists all of
+them, bind the shared runtime configuration and the full operation catalogue once with
+`createOperationsAppFactory()` and build a small app per route file from it:
+
+```ts
+// src/lib/api/app.ts
+import { createOperationsAppFactory, operationHttpMethods, toNextRouteHandlers } from "@schemavaults/openapi-operations";
+
+export const operations = [getApp, health]; // the catalogue buildOpenApiDocument() is given
+export const api = createOperationsAppFactory<{ dbh: Kysely<AuthDatabase> }, UserData>({
+  operations,
+  authResolvers,
+  context: async () => ({ dbh: await getDbh() }),
+});
+
+// app/api/apps/[app_id]/route.ts   (Next.js segment [app_id] ↔ OpenAPI {app_id})
+export const runtime = "nodejs";
+export const { GET } = toNextRouteHandlers(api.app([getApp]), operationHttpMethods([getApp]));
+
+// app/api/health/route.ts
+export const { GET } = toNextRouteHandlers(api.app([health]), operationHttpMethods([health]));
+
+// app/api/openapi.json/route.ts
+export const { GET } = toNextRouteHandlers(
+  api.openApiDocumentApp({ path: "/api/openapi.json", document: openApiDocument }),
+  ["get"],
+);
+```
+
+Each app routes on the full request pathname, so no `basePath` is needed and the
+dynamic segment is parsed by the app itself (Next.js' `params` are never read).
+`operationHttpMethods()` exports only the methods the operations declare, leaving 405s
+for the rest to Next.js. The factory validates the whole catalogue up front (unique
+operations, a resolver for every scheme) and `api.app()` throws for an operation that
+is not in it, so a route file cannot serve something the document does not describe.
+The reverse (a documented operation with no route file) is a file-layout question;
+the example resource server in this repository checks it with a small `bun test`.
+
 Per request the app: resolves the context, tries each accepted scheme's resolver in
 order (401 + `WWW-Authenticate` if none yields a principal), enforces the route guard
 (403), required scopes (403 `insufficient_scope`), organization membership (403), then

package/dist/adapters/nextjs.d.ts

@@ -5,8 +5,8 @@ export type NextRouteHandlers<TMethods extends HttpMethod = HttpMethod> = {
     readonly [M in TMethods as Uppercase<M>]: NextRouteHandler;
 };
 /**
- * Next.js App Router route-handler exports for the operations app. Typical
- * usage from a catch-all route so one Hono app serves every operation:
+ * Next.js App Router route-handler exports for the operations app. Either
+ * mount one app from a catch-all route so it serves every operation:
  *
  * ```ts
  * // app/api/[[...route]]/route.ts
@@ -14,7 +14,21 @@ export type NextRouteHandlers<TMethods extends HttpMethod = HttpMethod> = {
  * export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextRouteHandlers(app);
  * ```
  *
- * Pass `methods` to only export a subset (e.g. when a route file coexists
- * with hand-written handlers for other methods).
+ * or give each operation its own `route.ts` at the matching Next.js path
+ * (`app/api/apps/[app_id]/route.ts` for `/api/apps/{app_id}`) and mount an
+ * app built for just that operation, via `createOperationsAppFactory()`,
+ * exporting only the methods it declares so Next.js answers 405 for the
+ * rest:
+ *
+ * ```ts
+ * // app/api/apps/[app_id]/route.ts
+ * export const { GET } = toNextRouteHandlers(api.app([getApp]), operationHttpMethods([getApp]));
+ * ```
+ *
+ * The app receives the raw request, so it routes on the full pathname
+ * regardless of which route file it is exported from; no `basePath` is
+ * needed for per-route mounting. Pass `methods` to only export a subset
+ * (e.g. when a route file coexists with hand-written handlers for other
+ * methods).
  */
 export declare function toNextRouteHandlers<const TMethods extends readonly HttpMethod[] = typeof HTTP_METHODS>(app: Hono, methods?: TMethods): NextRouteHandlers<TMethods[number]>;

package/dist/adapters/nextjs.js

@@ -1,8 +1,8 @@
 import { handle } from "hono/vercel";
 import { HTTP_METHODS } from "../http-method";
 /**
- * Next.js App Router route-handler exports for the operations app. Typical
- * usage from a catch-all route so one Hono app serves every operation:
+ * Next.js App Router route-handler exports for the operations app. Either
+ * mount one app from a catch-all route so it serves every operation:
  *
  * ```ts
  * // app/api/[[...route]]/route.ts
@@ -10,8 +10,22 @@ import { HTTP_METHODS } from "../http-method";
  * export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextRouteHandlers(app);
  * ```
  *
- * Pass `methods` to only export a subset (e.g. when a route file coexists
- * with hand-written handlers for other methods).
+ * or give each operation its own `route.ts` at the matching Next.js path
+ * (`app/api/apps/[app_id]/route.ts` for `/api/apps/{app_id}`) and mount an
+ * app built for just that operation, via `createOperationsAppFactory()`,
+ * exporting only the methods it declares so Next.js answers 405 for the
+ * rest:
+ *
+ * ```ts
+ * // app/api/apps/[app_id]/route.ts
+ * export const { GET } = toNextRouteHandlers(api.app([getApp]), operationHttpMethods([getApp]));
+ * ```
+ *
+ * The app receives the raw request, so it routes on the full pathname
+ * regardless of which route file it is exported from; no `basePath` is
+ * needed for per-route mounting. Pass `methods` to only export a subset
+ * (e.g. when a route file coexists with hand-written handlers for other
+ * methods).
  */
 export function toNextRouteHandlers(app, methods = HTTP_METHODS) {
     const handler = handle(app);

package/dist/adapters/nextjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../../src/adapters/nextjs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC;AAQ/D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAS,EACT,UAAoB,YAAmC;IAEvD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAqC,EAAE,CAAC;IACtD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,OAAO,CAAC;IAC3C,CAAC;IACD,OAAO,QAA+C,CAAC;AACzD,CAAC"}
+{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../../src/adapters/nextjs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC;AAQ/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAS,EACT,UAAoB,YAAmC;IAEvD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAqC,EAAE,CAAC;IACtD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,OAAO,CAAC;IAC3C,CAAC;IACD,OAAO,QAA+C,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -1,13 +1,14 @@
-export { z } from "./zod-openapi";
-export type { ZodType, ZodObject } from "./zod-openapi";
+export { z, withOpenApi } from "./zod-openapi";
+export type { ZodType, ZodObject, OpenApiSchemaMetadata } from "./zod-openapi";
 export { HTTP_METHODS, HTTP_METHODS_WITH_REQUEST_BODY, isHttpMethod } from "./http-method";
 export type { HttpMethod } from "./http-method";
 export { defineAuthScheme, publicAccess, requireAuth, isPublicOperationAuth, ROUTE_GUARD_TYPES, schemaVaultsAccessTokenBearerScheme, schemaVaultsAccessTokenCookieScheme, schemaVaultsRefreshTokenCookieScheme, oidcClientSecretBasicScheme, oidcClientSecretPostScheme, apiKeyHeaderScheme, } from "./auth-scheme";
 export type { AuthSchemeDefinition, AuthRequirements, OperationAuth, PublicOperationAuth, RequiredOperationAuth, OrganizationRoleRequirement, RouteGuardType, } from "./auth-scheme";
-export { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, } from "./operation";
+export { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, operationHttpMethods, } from "./operation";
 export type { AnyOperationDefinition, AuthPrincipal, EmptyResponseStatusOf, InferBody, InferParsed, OperationDefiner, OperationDefinition, OperationGroup, OperationHandlerContext, OperationHandlerResult, OperationInput, OperationRequestDefinition, RequestBodyContentType, RequestBodyDefinition, ResponseBodyOf, ResponseDefinition, ResponseStatusOf, ResponsesDefinition, } from "./operation";
 export { buildOpenApiDocument, collectAuthSchemes, toRouteConfig, toSecuritySchemeComponent, } from "./openapi/build-openapi-document";
 export type { BuildOpenApiDocumentOptions } from "./openapi/build-openapi-document";
+export type { OpenAPIObject } from "openapi3-ts/oas31";
 export { SCHEMAVAULTS_AUTH_EXTENSION, SCHEMAVAULTS_SCHEME_TITLE_EXTENSION, SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION, toSchemaVaultsAuthExtension, isSchemaVaultsAuthExtension, } from "./openapi/extensions";
 export type { SchemaVaultsAuthExtension } from "./openapi/extensions";
 export { extractPathParameterNames, openApiPathToHonoPath, honoPathToOpenApiPath, isOpenApiPath, } from "./openapi/path-format";

package/dist/index.js

@@ -1,7 +1,7 @@
-export { z } from "./zod-openapi";
+export { z, withOpenApi } from "./zod-openapi";
 export { HTTP_METHODS, HTTP_METHODS_WITH_REQUEST_BODY, isHttpMethod } from "./http-method";
 export { defineAuthScheme, publicAccess, requireAuth, isPublicOperationAuth, ROUTE_GUARD_TYPES, schemaVaultsAccessTokenBearerScheme, schemaVaultsAccessTokenCookieScheme, schemaVaultsRefreshTokenCookieScheme, oidcClientSecretBasicScheme, oidcClientSecretPostScheme, apiKeyHeaderScheme, } from "./auth-scheme";
-export { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, } from "./operation";
+export { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, operationHttpMethods, } from "./operation";
 export { buildOpenApiDocument, collectAuthSchemes, toRouteConfig, toSecuritySchemeComponent, } from "./openapi/build-openapi-document";
 export { SCHEMAVAULTS_AUTH_EXTENSION, SCHEMAVAULTS_SCHEME_TITLE_EXTENSION, SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION, toSchemaVaultsAuthExtension, isSchemaVaultsAuthExtension, } from "./openapi/extensions";
 export { extractPathParameterNames, openApiPathToHonoPath, honoPathToOpenApiPath, isOpenApiPath, } from "./openapi/path-format";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAE,8BAA8B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mCAAmC,EACnC,mCAAmC,EACnC,oCAAoC,EACpC,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAWvB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAsBrB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,2BAA2B,EAC3B,mCAAmC,EACnC,uCAAuC,EACvC,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,cAAc,WAAW,CAAC;AAI1B,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,8BAA8B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mCAAmC,EACnC,mCAAmC,EACnC,oCAAoC,EACpC,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAWvB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAsBrB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EACL,2BAA2B,EAC3B,mCAAmC,EACnC,uCAAuC,EACvC,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,cAAc,WAAW,CAAC;AAI1B,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/operation.d.ts

@@ -3,13 +3,30 @@ import type { OrganizationMembershipRoleType } from "@schemavaults/auth-common/o
 import { type HttpMethod } from "./http-method";
 import type { OperationAuth, PublicOperationAuth } from "./auth-scheme";
 export type RequestBodyContentType = "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | (string & {});
-export interface RequestBodyDefinition<TSchema extends ZodType = ZodType> {
+export interface RequestBodyDefinition<TSchema extends ZodType = ZodType, TDocumentOnly extends boolean = boolean> {
     /** Media type the body is parsed as (default `application/json`). */
     readonly contentType?: RequestBodyContentType;
     readonly schema: TSchema;
     readonly description?: string;
     /** Default true. */
     readonly required?: boolean;
+    /**
+     * Also parse the body as `contentType` when the request labels it
+     * `text/plain` or carries no Content-Type header at all. Browsers send
+     * `text/plain;charset=UTF-8` for `fetch(url, { body: JSON.stringify(x) })`
+     * without an explicit header, so JSON APIs with such callers need this.
+     * Default false (415 on a media type mismatch).
+     */
+    readonly lenientContentType?: boolean;
+    /**
+     * Describe the body in the OpenAPI document but leave the request
+     * untouched: the runtime neither reads nor validates it and `ctx.body`
+     * is `undefined`, so the handler reads `ctx.request` itself. For
+     * endpoints whose error format is mandated by a protocol (the OAuth 2.0
+     * token endpoint's `{ error, error_description }`, ...) and endpoints
+     * with bespoke parsing that must keep its exact responses.
+     */
+    readonly documentOnly?: TDocumentOnly;
 }
 export interface ResponseDefinition<TSchema extends ZodType | undefined = ZodType | undefined> {
     readonly description: string;
@@ -31,7 +48,9 @@ export interface OperationRequestDefinition<TParams extends ZodObject | undefine
     readonly body?: TBody;
 }
 export type InferParsed<T> = T extends ZodType ? z.output<T> : Readonly<Record<string, never>>;
-export type InferBody<T> = T extends RequestBodyDefinition<infer S> ? S extends ZodType ? z.output<S> : undefined : undefined;
+export type InferBody<T> = T extends {
+    readonly documentOnly: true;
+} ? undefined : T extends RequestBodyDefinition<infer S> ? S extends ZodType ? z.output<S> : undefined : undefined;
 export type ResponseStatusOf<TResponses extends ResponsesDefinition> = Extract<keyof TResponses, number>;
 export type ResponseBodyOf<TResponses extends ResponsesDefinition, S extends keyof TResponses> = TResponses[S] extends {
     readonly schema: infer TSchema;
@@ -165,4 +184,10 @@ export interface OperationGroup {
  * `createOperationsApp` like any other operation list.
  */
 export declare function defineOperationGroup(group: OperationGroup): AnyOperationDefinition[];
+/**
+ * Distinct HTTP methods declared by the given operations, in declaration
+ * order. Hands `toNextRouteHandlers()` exactly the methods a route file
+ * should export, so Next.js answers 405 for the others itself.
+ */
+export declare function operationHttpMethods(operations: readonly AnyOperationDefinition[]): HttpMethod[];
 export declare function assertUniqueOperations(operations: readonly AnyOperationDefinition[]): void;

package/dist/operation.js

@@ -93,6 +93,14 @@ export function defineOperationGroup(group) {
         return Object.freeze({ ...operation, path, tags });
     });
 }
+/**
+ * Distinct HTTP methods declared by the given operations, in declaration
+ * order. Hands `toNextRouteHandlers()` exactly the methods a route file
+ * should export, so Next.js answers 405 for the others itself.
+ */
+export function operationHttpMethods(operations) {
+    return Array.from(new Set(operations.map((operation) => operation.method)));
+}
 export function assertUniqueOperations(operations) {
     const ids = new Set();
     const routes = new Set();

package/dist/operation.js.map

@@ -1 +1 @@
-{"version":3,"file":"operation.js","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,8BAA8B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9F,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA+RjF,MAAM,UAAU,kBAAkB,CAAC,MAAkB,EAAE,IAAY;IACjE,MAAM,IAAI,GAAG,IAAI;SACd,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;SACvC,IAAI,CAAC,GAAG,CAAC;SACT,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC;AAED,SAAS,sBAAsB,CAAC,KAM/B;IACC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,4BAA4B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,mBAAmB,KAAK,CAAC,IAAI,oDAAoD,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,SAAS,CAAC,aAAa,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,kBAAkB,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,YAAY,GAAG,yBAAyB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAa,KAAK,CAAC,OAAO,EAAE,MAAM;QAC9C,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;QACzC,CAAC,CAAC,EAAE,CAAC;IACP,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,SAAS,CACjB,mBAAmB,IAAI,QAAQ,KAAK,CAAC,IAAI,oCAAoC,CAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,4BAA4B,IAAI,SAAS,KAAK,CAAC,IAAI,YAAY,IAAI,eAAe,CACnF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,8BAA8B,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,gEAAgE,CAC5G,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,wBAAwB,CAAC,CAAC;IAC3F,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,GAAG,IAAI,IAAI,GAAG,GAAG,EAAE,CAAC;YACxD,MAAM,IAAI,SAAS,CAAC,4BAA4B,MAAM,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB;IAIpC,OAAO,SAAS,yBAAyB,CAAC,KAAK;QAC7C,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,SAAS,GAAG;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC;YAC9E,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;YAC5C,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;YAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAAkD,CAAC;IACnF,CAAsC,CAAC;AACzC,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAC1B,sBAAsB,EAAoB,CAAC;AAc7C;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAqB;IACxD,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;IACtC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,qBAAqB,MAAM,uBAAuB,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAA0B,EAAE;QAChE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;QACnG,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7E,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,UAA6C;IAClF,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,SAAS,CAAC,0BAA0B,SAAS,CAAC,WAAW,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC,mBAAmB,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;AACH,CAAC"}
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"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"}

package/dist/runtime/create-operations-app-factory.d.ts

@@ -0,0 +1,69 @@
+import type { Hono } from "hono";
+import type { AnyOperationDefinition } from "../operation";
+import { type CreateOperationsAppOptions, type OpenApiDocumentRouteOptions } from "./create-operations-app";
+import { type AuthResolvers } from "./resolve-auth";
+export interface CreateOperationsAppFactoryOptions<TContext = unknown, TUser = unknown> {
+    /**
+     * Every operation the API exposes: the catalogue `buildOpenApiDocument()`
+     * is given. Apps built by the factory may only serve operations from it,
+     * so a route file cannot mount an operation the document does not list.
+     */
+    readonly operations: readonly AnyOperationDefinition[];
+    /** Credential resolvers keyed by auth scheme name, shared by every app. */
+    readonly authResolvers?: AuthResolvers<TUser, TContext>;
+    /** Builds the per-request context handed to handlers as `ctx.context`. */
+    readonly context?: CreateOperationsAppOptions<TContext, TUser>["context"];
+    /** Releases the per-request context once the response was produced. */
+    readonly disposeContext?: CreateOperationsAppOptions<TContext, TUser>["disposeContext"];
+    /** Called for unexpected (non-OperationError) failures before the 500 is sent. */
+    readonly onError?: CreateOperationsAppOptions<TContext, TUser>["onError"];
+}
+/** Per-app options a factory caller may still set. */
+export type OperationsAppFactoryAppOptions<TContext = unknown, TUser = unknown> = Pick<CreateOperationsAppOptions<TContext, TUser>, "basePath" | "configure" | "openapi">;
+export interface OperationsAppFactory<TContext = unknown, TUser = unknown> {
+    /** The full catalogue the factory was created with. */
+    readonly operations: readonly AnyOperationDefinition[];
+    /** The shared resolvers every app built by the factory authenticates with. */
+    readonly authResolvers: AuthResolvers<TUser, TContext>;
+    /**
+     * Builds a Hono app serving the given operations (default: the whole
+     * catalogue) with the shared resolvers / context / error reporting.
+     * Throws when an operation is not part of the catalogue.
+     */
+    app(operations?: readonly AnyOperationDefinition[], options?: OperationsAppFactoryAppOptions<TContext, TUser>): Hono;
+    /** Builds a Hono app that only serves the OpenAPI document. */
+    openApiDocumentApp(openapi: OpenApiDocumentRouteOptions, options?: Omit<OperationsAppFactoryAppOptions<TContext, TUser>, "openapi">): Hono;
+    /** Throws unless every given operation is part of the catalogue. */
+    assertRegistered(operations: readonly AnyOperationDefinition[]): void;
+}
+/**
+ * Binds the shared runtime configuration (auth resolvers, per-request
+ * context, error reporting) and the full operation catalogue once, so many
+ * small apps can be built from it: one per Next.js `route.ts` / Vercel
+ * function file, each serving only the operation(s) at its path, while a
+ * single OpenAPI document generated from the same catalogue still describes
+ * all of them.
+ *
+ * ```ts
+ * // src/lib/api/app.ts
+ * export const api = createOperationsAppFactory<Ctx, UserData>({
+ *   operations, // the same list buildOpenApiDocument() is given
+ *   authResolvers,
+ *   context: () => ({ ... }),
+ * });
+ *
+ * // app/api/health/route.ts
+ * export const { GET } = toNextRouteHandlers(api.app([health]), operationHttpMethods([health]));
+ *
+ * // app/api/openapi.json/route.ts
+ * export const { GET } = toNextRouteHandlers(
+ *   api.openApiDocumentApp({ path: "/api/openapi.json", document }),
+ *   ["get"],
+ * );
+ * ```
+ *
+ * Every app validates against the whole catalogue up front: duplicate
+ * operations or a scheme without a resolver fail at module load of the
+ * first route rather than when the affected route is first hit.
+ */
+export declare function createOperationsAppFactory<TContext = unknown, TUser = unknown>(options: CreateOperationsAppFactoryOptions<TContext, TUser>): OperationsAppFactory<TContext, TUser>;

package/dist/runtime/create-operations-app-factory.js

@@ -0,0 +1,68 @@
+import { assertUniqueOperations } from "../operation";
+import { createOperationsApp, } from "./create-operations-app";
+import { assertResolversForOperations } from "./resolve-auth";
+/**
+ * Binds the shared runtime configuration (auth resolvers, per-request
+ * context, error reporting) and the full operation catalogue once, so many
+ * small apps can be built from it: one per Next.js `route.ts` / Vercel
+ * function file, each serving only the operation(s) at its path, while a
+ * single OpenAPI document generated from the same catalogue still describes
+ * all of them.
+ *
+ * ```ts
+ * // src/lib/api/app.ts
+ * export const api = createOperationsAppFactory<Ctx, UserData>({
+ *   operations, // the same list buildOpenApiDocument() is given
+ *   authResolvers,
+ *   context: () => ({ ... }),
+ * });
+ *
+ * // app/api/health/route.ts
+ * export const { GET } = toNextRouteHandlers(api.app([health]), operationHttpMethods([health]));
+ *
+ * // app/api/openapi.json/route.ts
+ * export const { GET } = toNextRouteHandlers(
+ *   api.openApiDocumentApp({ path: "/api/openapi.json", document }),
+ *   ["get"],
+ * );
+ * ```
+ *
+ * Every app validates against the whole catalogue up front: duplicate
+ * operations or a scheme without a resolver fail at module load of the
+ * first route rather than when the affected route is first hit.
+ */
+export function createOperationsAppFactory(options) {
+    const catalogue = Object.freeze([...options.operations]);
+    assertUniqueOperations(catalogue);
+    const resolvers = options.authResolvers ?? {};
+    assertResolversForOperations(catalogue, resolvers);
+    const registered = new Set(catalogue);
+    const assertRegistered = (operations) => {
+        for (const operation of operations) {
+            if (!registered.has(operation)) {
+                throw new TypeError(`${operation.method.toUpperCase()} ${operation.path} (${operation.operationId}) is not part of the operations catalogue this factory was created with, so it would be served without appearing in the OpenAPI document`);
+            }
+        }
+    };
+    const app = (operations = catalogue, appOptions = {}) => {
+        assertRegistered(operations);
+        return createOperationsApp({
+            operations,
+            authResolvers: resolvers,
+            context: options.context,
+            disposeContext: options.disposeContext,
+            onError: options.onError,
+            basePath: appOptions.basePath,
+            configure: appOptions.configure,
+            openapi: appOptions.openapi,
+        });
+    };
+    return {
+        operations: catalogue,
+        authResolvers: resolvers,
+        app,
+        openApiDocumentApp: (openapi, appOptions = {}) => app([], { ...appOptions, openapi }),
+        assertRegistered,
+    };
+}
+//# sourceMappingURL=create-operations-app-factory.js.map

package/dist/runtime/create-operations-app-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-operations-app-factory.js","sourceRoot":"","sources":["../../src/runtime/create-operations-app-factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,mBAAmB,GAGpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,4BAA4B,EAAsB,MAAM,gBAAgB,CAAC;AAgDlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA2D;IAE3D,MAAM,SAAS,GAAsC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5F,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,SAAS,GAAmC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAC9E,4BAA4B,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAyB,SAAS,CAAC,CAAC;IAE9D,MAAM,gBAAgB,GAAG,CAAC,UAA6C,EAAQ,EAAE;QAC/E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,SAAS,CACjB,GAAG,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,WAAW,0IAA0I,CACxN,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,GAAG,GAAiD,CACxD,UAAU,GAAG,SAAS,EACtB,UAAU,GAAG,EAAE,EACf,EAAE;QACF,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAC7B,OAAO,mBAAmB,CAAkB;YAC1C,UAAU;YACV,aAAa,EAAE,SAAS;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,SAAS,EAAE,UAAU,CAAC,SAAS;YAC/B,OAAO,EAAE,UAAU,CAAC,OAAO;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,UAAU,EAAE,SAAS;QACrB,aAAa,EAAE,SAAS;QACxB,GAAG;QACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,UAAU,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,CAAC;QACrF,gBAAgB;KACjB,CAAC;AACJ,CAAC"}

package/dist/runtime/create-operations-app.d.ts

@@ -12,23 +12,41 @@ export interface OpenApiDocumentRouteOptions {
      */
     readonly document: OpenAPIObject | ((c: Context) => OpenAPIObject | Promise<OpenAPIObject>);
 }
+/** What `onError` learns about the failed request besides the error itself. */
+export interface OperationFailureInfo<TContext = unknown> {
+    readonly operation: AnyOperationDefinition;
+    /** The per-request context, when it had been built before the failure. */
+    readonly context: TContext | undefined;
+}
 export interface CreateOperationsAppOptions<TContext = unknown, TUser = unknown> {
     readonly operations: readonly AnyOperationDefinition[];
     /**
      * Prefix stripped by the deployment before routing (e.g. `/api` when the
      * app is mounted from `app/api/[[...route]]/route.ts`). Operation paths
      * stay absolute in the OpenAPI document; leave unset to route on them
-     * verbatim.
+     * verbatim (Next.js route handlers and Vercel functions receive the full
+     * request URL, so they never need it).
      */
     readonly basePath?: string;
     /** Credential resolvers keyed by auth scheme name. */
-    readonly authResolvers?: AuthResolvers<TUser>;
-    /** Builds the per-request context handed to handlers as `ctx.context`. */
+    readonly authResolvers?: AuthResolvers<TUser, TContext>;
+    /**
+     * Builds the per-request context handed to auth resolvers and to handlers
+     * as `ctx.context`. Built before credentials are resolved, so it should
+     * be cheap (open expensive resources lazily) and is released through
+     * `disposeContext` once the response has been produced.
+     */
     readonly context?: (c: Context) => Promise<TContext> | TContext;
+    /**
+     * Releases the per-request context (database handles, cache connections)
+     * after the handler returned or failed. Errors thrown here are reported
+     * to `onError` (or the console) and never change the response.
+     */
+    readonly disposeContext?: (context: TContext, c: Context) => void | Promise<void>;
     /** Serve the OpenAPI document from the app; omit to not expose it. */
     readonly openapi?: OpenApiDocumentRouteOptions;
     /** Called for unexpected (non-OperationError) failures before the 500 is sent. */
-    readonly onError?: (error: unknown, c: Context) => void | Promise<void>;
+    readonly onError?: (error: unknown, c: Context, info: OperationFailureInfo<TContext>) => void | Promise<void>;
     /** Extra middleware / routes registered before the operations (CORS, logging, ...). */
     readonly configure?: (app: Hono) => void;
 }

package/dist/runtime/create-operations-app.js

@@ -52,11 +52,29 @@ export function createOperationsApp(options) {
             return c.json(resolved);
         });
     }
+    const report = async (error, c, info) => {
+        if (options.onError) {
+            try {
+                await options.onError(error, c, info);
+            }
+            catch {
+                // never let error reporting mask the response
+            }
+        }
+        else {
+            console.error(`[openapi-operations] ${info.operation.method.toUpperCase()} ${info.operation.path} failed:`, error);
+        }
+    };
     for (const operation of options.operations) {
         app.on(operation.method.toUpperCase(), openApiPathToHonoPath(operation.path), async (c) => {
+            let context = undefined;
+            let built = false;
             try {
-                const context = options.context ? await options.context(c) : undefined;
-                const auth = await resolveAuth(c, operation.auth, resolvers);
+                if (options.context) {
+                    context = await options.context(c);
+                    built = true;
+                }
+                const auth = await resolveAuth(c, operation.auth, resolvers, context);
                 const validated = await validateRequest(c, operation);
                 const ctx = buildHandlerContext(c, operation, validated, auth, context);
                 const result = await operation.handler(ctx);
@@ -68,23 +86,23 @@ export function createOperationsApp(options) {
             catch (error) {
                 if (error instanceof OperationError)
                     return error.toResponse();
-                if (options.onError) {
-                    try {
-                        await options.onError(error, c);
-                    }
-                    catch {
-                        // never let error reporting mask the response
-                    }
-                }
-                else {
-                    console.error(`[openapi-operations] ${operation.method.toUpperCase()} ${operation.path} failed:`, error);
-                }
+                await report(error, c, { operation, context });
                 return jsonResponse(500, {
                     success: false,
                     error: OPERATION_ERROR_CODES.internal,
                     message: "Internal Server Error",
                 });
             }
+            finally {
+                if (built && options.disposeContext) {
+                    try {
+                        await options.disposeContext(context, c);
+                    }
+                    catch (error) {
+                        await report(error, c, { operation, context });
+                    }
+                }
+            }
         });
     }
     return root;

package/dist/runtime/create-operations-app.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-operations-app.js","sourceRoot":"","sources":["../../src/runtime/create-operations-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAgB,MAAM,MAAM,CAAC;AAG1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,4BAA4B,EAAE,WAAW,EAAsB,MAAM,gBAAgB,CAAC;AA8C/F,SAAS,mBAAmB,CAC1B,CAAU,EACV,SAAiC,EACjC,SAA+E,EAC/E,IAAa,EACb,OAAgB;IAEhB,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/E,MAAM,cAAc,GAAG,CAAC,MAAc,EAAQ,EAAE;QAC9C,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,SAAS,CACjB,GAAG,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,IAAI,qCAAqC,MAAM,EAAE,CACjG,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;IACF,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,IAAI;QACJ,OAAO;QACP,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG;QAClB,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI;YACrB,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,OAAO,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACnD,CAAC;QACD,KAAK,CAAC,MAAM,EAAE,IAAI;YAChB,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;YAC7B,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAoD;IAEpD,sBAAsB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAyB,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IACpE,4BAA4B,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAE5D,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IAEzB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;QAC7D,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;YACxB,MAAM,QAAQ,GAAG,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC/E,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,GAAG,CAAC,EAAE,CACJ,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,EAC9B,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC,EACrC,KAAK,EAAE,CAAU,EAAqB,EAAE;YACtC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,SAAsB,CAAC;gBACrF,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBAC7D,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;gBACtD,MAAM,GAAG,GAAG,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;gBACxE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC5C,IAAI,CAAC,CAAC,MAAM,YAAY,QAAQ,CAAC,EAAE,CAAC;oBAClC,MAAM,IAAI,SAAS,CACjB,GAAG,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,IAAI,4DAA4D,CAChH,CAAC;gBACJ,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,IAAI,KAAK,YAAY,cAAc;oBAAE,OAAO,KAAK,CAAC,UAAU,EAAE,CAAC;gBAC/D,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;oBACpB,IAAI,CAAC;wBACH,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;oBAClC,CAAC;oBAAC,MAAM,CAAC;wBACP,8CAA8C;oBAChD,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,KAAK,CACX,wBAAwB,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,IAAI,UAAU,EAClF,KAAK,CACN,CAAC;gBACJ,CAAC;gBACD,OAAO,YAAY,CAAC,GAAG,EAAE;oBACvB,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,qBAAqB,CAAC,QAAQ;oBACrC,OAAO,EAAE,uBAAuB;iBACjC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"create-operations-app.js","sourceRoot":"","sources":["../../src/runtime/create-operations-app.ts"],"names":[],"mappings":"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"}

package/dist/runtime/index.d.ts

@@ -1,5 +1,7 @@
 export { createOperationsApp } from "./create-operations-app";
-export type { CreateOperationsAppOptions, OpenApiDocumentRouteOptions, } from "./create-operations-app";
+export type { CreateOperationsAppOptions, OpenApiDocumentRouteOptions, OperationFailureInfo, } from "./create-operations-app";
+export { createOperationsAppFactory } from "./create-operations-app-factory";
+export type { CreateOperationsAppFactoryOptions, OperationsAppFactory, OperationsAppFactoryAppOptions, } from "./create-operations-app-factory";
 export { OperationError, OPERATION_ERROR_CODES, jsonResponse } from "./errors";
 export type { OperationErrorBody, OperationValidationIssue } from "./errors";
 export { resolveAuth, grantedScopes, missingScopes } from "./resolve-auth";

package/dist/runtime/index.js

@@ -1,4 +1,5 @@
 export { createOperationsApp } from "./create-operations-app";
+export { createOperationsAppFactory } from "./create-operations-app-factory";
 export { OperationError, OPERATION_ERROR_CODES, jsonResponse } from "./errors";
 export { resolveAuth, grantedScopes, missingScopes } from "./resolve-auth";
 export { validateRequest, queryToObject, headersToObject, readRequestBody } from "./validate-request";

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAK9D,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAM9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAM7E,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/runtime/resolve-auth.d.ts

@@ -5,11 +5,13 @@ import type { AnyOperationDefinition, AuthPrincipal } from "../operation";
  * Verifies the credential transported by one auth scheme. Returns null when
  * the request carries no credential for the scheme (so the next accepted
  * scheme is tried); throws {@link OperationError} to reject outright (e.g.
- * a credential that IS present but invalid).
+ * a credential that IS present but invalid). Receives the per-request
+ * context built by `createOperationsApp({ context })` so it can share the
+ * request's database handle / caches with the handler.
  */
-export type AuthResolver<TUser = unknown> = (c: Context, scheme: AuthSchemeDefinition) => Promise<AuthPrincipal<TUser> | null> | AuthPrincipal<TUser> | null;
-export type AuthResolvers<TUser = unknown> = Readonly<Record<string, AuthResolver<TUser>>>;
-export declare function assertResolversForOperations(operations: readonly AnyOperationDefinition[], resolvers: AuthResolvers): void;
+export type AuthResolver<TUser = unknown, TContext = unknown> = (c: Context, scheme: AuthSchemeDefinition, context: TContext) => Promise<AuthPrincipal<TUser> | null> | AuthPrincipal<TUser> | null;
+export type AuthResolvers<TUser = unknown, TContext = unknown> = Readonly<Record<string, AuthResolver<TUser, TContext>>>;
+export declare function assertResolversForOperations(operations: readonly AnyOperationDefinition[], resolvers: AuthResolvers<any, any>): void;
 export declare function grantedScopes(principal: AuthPrincipal): string[];
 export declare function missingScopes(principal: AuthPrincipal, required: readonly string[]): string[];
 /**
@@ -18,4 +20,4 @@ export declare function missingScopes(principal: AuthPrincipal, required: readon
  * required scopes, and organization membership. Returns the principal, or
  * null for public operations.
  */
-export declare function resolveAuth<TUser>(c: Context, auth: OperationAuth, resolvers: AuthResolvers<TUser>): Promise<AuthPrincipal<TUser> | null>;
+export declare function resolveAuth<TUser, TContext = unknown>(c: Context, auth: OperationAuth, resolvers: AuthResolvers<TUser, TContext>, context?: TContext): Promise<AuthPrincipal<TUser> | null>;

package/dist/runtime/resolve-auth.js

@@ -1,5 +1,7 @@
 import { OPERATION_ERROR_CODES, OperationError } from "./errors";
-export function assertResolversForOperations(operations, resolvers) {
+export function assertResolversForOperations(operations, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+resolvers) {
     for (const operation of operations) {
         if (operation.auth.type !== "required")
             continue;
@@ -31,7 +33,7 @@ export function missingScopes(principal, required) {
  * required scopes, and organization membership. Returns the principal, or
  * null for public operations.
  */
-export async function resolveAuth(c, auth, resolvers) {
+export async function resolveAuth(c, auth, resolvers, context = undefined) {
     if (auth.type === "public")
         return null;
     let principal = null;
@@ -39,7 +41,7 @@ export async function resolveAuth(c, auth, resolvers) {
         const resolver = resolvers[scheme.name];
         if (!resolver)
             continue;
-        principal = await resolver(c, scheme);
+        principal = await resolver(c, scheme, context);
         if (principal)
             break;
     }

package/dist/runtime/resolve-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-auth.js","sourceRoot":"","sources":["../../src/runtime/resolve-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve-auth.js","sourceRoot":"","sources":["../../src/runtime/resolve-auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAoBjE,MAAM,UAAU,4BAA4B,CAC1C,UAA6C;AAC7C,8DAA8D;AAC9D,SAAkC;IAElC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACjD,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5C,IAAI,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;gBACjD,MAAM,IAAI,SAAS,CACjB,GAAG,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,IAAI,yBAAyB,MAAM,CAAC,IAAI,yCAAyC,CACjI,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,OAAwC;IAC/D,MAAM,UAAU,GAAG,OAAO;SACvB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;SACjC,MAAM,CAAC,CAAC,SAAS,EAAuB,EAAE,CAAC,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC;IAC7E,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAwB;IACpD,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACnD,OAAO,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAwB,EAAE,QAA2B;IACjF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;IAClD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,CAAU,EACV,IAAmB,EACnB,SAAyC,EACzC,UAAoB,SAAqB;IAEzC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAExC,IAAI,SAAS,GAAgC,IAAI,CAAC;IAClD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,SAAS,GAAG,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,SAAS;YAAE,MAAM;IACvB,CAAC;IACD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,cAAc,CACtB,GAAG,EACH,EAAE,KAAK,EAAE,qBAAqB,CAAC,YAAY,EAAE,OAAO,EAAE,yBAAyB,EAAE,EACjF,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAC9B,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,eAAe,CAAC,KAAK,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QAC3E,MAAM,IAAI,cAAc,CAAC,GAAG,EAAE;YAC5B,KAAK,EAAE,qBAAqB,CAAC,SAAS;YACtC,OAAO,EAAE,+BAA+B;SACzC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;IAC3C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACnD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CACtB,GAAG,EACH;gBACE,KAAK,EAAE,qBAAqB,CAAC,iBAAiB;gBAC9C,OAAO,EAAE,0DAA0D,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;gBACtF,OAAO,EAAE,EAAE,eAAe,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE;aACrE,EACD;gBACE,kBAAkB,EAAE,6CAA6C,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG;aACvF,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC;QAC5D,MAAM,cAAc,GAClB,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;QAChE,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,cAAc,CAAC,GAAG,EAAE;gBAC5B,KAAK,EAAE,qBAAqB,CAAC,oBAAoB;gBACjD,OAAO,EAAE,sBAAsB,SAAS,iCAAiC;aAC1E,CAAC,CAAC;QACL,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC;QAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,SAAS,CAAC,mBAAmB;gBACxC,CAAC,CAAC,MAAM,SAAS,CAAC,mBAAmB,CAAC,cAAc,CAAC;gBACrD,CAAC,CAAC,KAAK,CAAC;YACV,MAAM,OAAO,GACX,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAK,KAA2B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YACxF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,cAAc,CAAC,GAAG,EAAE;oBAC5B,KAAK,EAAE,qBAAqB,CAAC,SAAS;oBACtC,OAAO,EACL,KAAK,CAAC,MAAM,KAAK,CAAC;wBAChB,CAAC,CAAC,2CAA2C;wBAC7C,CAAC,CAAC,0DAA0D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;iBACnF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/runtime/validate-request.js

@@ -50,6 +50,10 @@ export async function readRequestBody(c, definition) {
     const actual = mediaTypeOf(c);
     const contentLength = c.req.header("content-length");
     const looksEmpty = actual === null && (contentLength === undefined || contentLength === "0");
+    const lenient = definition.lenientContentType === true;
+    // A body labelled text/plain (or not labelled at all) is re-parsed as the
+    // expected media type when the operation opted into leniency.
+    const relabelled = lenient && (actual === null || actual === "text/plain");
     if (looksEmpty) {
         if (!required)
             return undefined;
@@ -61,7 +65,9 @@ export async function readRequestBody(c, definition) {
             ],
         });
     }
-    if (actual !== expected && !(expected === "text/plain" && actual?.startsWith("text/"))) {
+    if (actual !== expected &&
+        !relabelled &&
+        !(expected === "text/plain" && actual?.startsWith("text/"))) {
         throw new OperationError(415, {
             error: OPERATION_ERROR_CODES.unsupportedMediaType,
             message: `Expected a ${expected} request body but received ${actual ?? "none"}`,
@@ -70,15 +76,21 @@ export async function readRequestBody(c, definition) {
     try {
         switch (expected) {
             case "application/json":
-                return await c.req.json();
+                // c.req.json() trusts the declared media type; parse the raw text
+                // ourselves so relabelled text/plain bodies work too.
+                return JSON.parse(await c.req.text());
             case "application/x-www-form-urlencoded":
+                if (relabelled) {
+                    return Object.fromEntries(new URLSearchParams(await c.req.text()));
+                }
+                return await c.req.parseBody({ all: true });
             case "multipart/form-data":
                 return await c.req.parseBody({ all: true });
             case "text/plain":
                 return await c.req.text();
             default:
                 if (expected.endsWith("+json"))
-                    return await c.req.json();
+                    return JSON.parse(await c.req.text());
                 return await c.req.text();
         }
     }
@@ -110,7 +122,7 @@ export async function validateRequest(c, operation) {
         ? (await parseWith(headers, headersToObject(c), "headers"))
         : EMPTY;
     let parsedBody = undefined;
-    if (body) {
+    if (body && body.documentOnly !== true) {
         const raw = await readRequestBody(c, body);
         if (raw !== undefined || (body.required ?? true)) {
             parsedBody = await parseWith(body.schema, raw, "body");

package/dist/runtime/validate-request.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-request.js","sourceRoot":"","sources":["../../src/runtime/validate-request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate-request.js","sourceRoot":"","sources":["../../src/runtime/validate-request.ts"],"names":[],"mappings":"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"}

package/dist/zod-openapi.d.ts

@@ -8,6 +8,27 @@
  * `z` from here (or call `extendZodWithOpenApi` themselves on the same zod
  * instance) instead of importing zod directly.
  */
-import { z } from "zod";
+import { z, type ZodType } from "zod";
+import { type ZodOpenAPIMetadata } from "@asteasolutions/zod-to-openapi";
 export { z };
 export type { ZodType, ZodObject } from "zod";
+export type OpenApiSchemaMetadata = Partial<ZodOpenAPIMetadata>;
+/**
+ * `schema.openapi(...)` for schemas built BEFORE this package was evaluated.
+ *
+ * zod v4 copies `ZodType.prototype` methods onto each schema instance when it
+ * is constructed, so a schema exported by another package (e.g.
+ * `@schemavaults/auth-common`) only has its own `.openapi` when that package
+ * happened to be evaluated after this one — which depends on the import order
+ * of whichever bundle loads first and throws `... .openapi is not a function`
+ * at module load otherwise. Invoking the prototype method explicitly sidesteps
+ * that: it returns a fresh copy of the schema carrying the metadata, exactly
+ * like a direct call would. Use it for every schema you did not build with the
+ * `z` exported from here.
+ *
+ * ```ts
+ * export const App = withOpenApi(schemaVaultsAppDefinitionSchema, "App", { description: "..." });
+ * const params = z.object({ app_id: withOpenApi(appIdSchema, { example: "my-app" }) });
+ * ```
+ */
+export declare function withOpenApi<T extends ZodType>(schema: T, refIdOrMetadata: string | OpenApiSchemaMetadata, metadata?: OpenApiSchemaMetadata): T;

package/dist/zod-openapi.js

@@ -9,7 +9,31 @@
  * instance) instead of importing zod directly.
  */
 import { z } from "zod";
-import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { extendZodWithOpenApi, } from "@asteasolutions/zod-to-openapi";
 extendZodWithOpenApi(z);
 export { z };
+/**
+ * `schema.openapi(...)` for schemas built BEFORE this package was evaluated.
+ *
+ * zod v4 copies `ZodType.prototype` methods onto each schema instance when it
+ * is constructed, so a schema exported by another package (e.g.
+ * `@schemavaults/auth-common`) only has its own `.openapi` when that package
+ * happened to be evaluated after this one — which depends on the import order
+ * of whichever bundle loads first and throws `... .openapi is not a function`
+ * at module load otherwise. Invoking the prototype method explicitly sidesteps
+ * that: it returns a fresh copy of the schema carrying the metadata, exactly
+ * like a direct call would. Use it for every schema you did not build with the
+ * `z` exported from here.
+ *
+ * ```ts
+ * export const App = withOpenApi(schemaVaultsAppDefinitionSchema, "App", { description: "..." });
+ * const params = z.object({ app_id: withOpenApi(appIdSchema, { example: "my-app" }) });
+ * ```
+ */
+export function withOpenApi(schema, refIdOrMetadata, metadata) {
+    const openapi = z.ZodType.prototype.openapi;
+    return typeof refIdOrMetadata === "string"
+        ? openapi.call(schema, refIdOrMetadata, metadata)
+        : openapi.call(schema, refIdOrMetadata);
+}
 //# sourceMappingURL=zod-openapi.js.map

package/dist/zod-openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"zod-openapi.js","sourceRoot":"","sources":["../src/zod-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAEtE,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAExB,OAAO,EAAE,CAAC,EAAE,CAAC"}
+{"version":3,"file":"zod-openapi.js","sourceRoot":"","sources":["../src/zod-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAC;AACtC,OAAO,EACL,oBAAoB,GAErB,MAAM,gCAAgC,CAAC;AAExC,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAExB,OAAO,EAAE,CAAC,EAAE,CAAC;AAOb;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CACzB,MAAS,EACT,eAA+C,EAC/C,QAAgC;IAEhC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,OAAgE,CAAC;IACrG,OAAO,OAAO,eAAe,KAAK,QAAQ;QACxC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,CAAC;QACjD,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schemavaults/openapi-operations",
   "description": "Define OpenAPI-representable HTTP operations (zod schemas + auth schemes + handlers) and serve them as Hono apps on Vercel functions / Next.js route handlers",
-  "version": "0.1.9",
+  "version": "0.3.0",
   "license": "UNLICENSED",
   "private": false,
   "repository": {