@voyant-travel/hono 0.116.2 → 0.117.1

package/dist/app.d.ts

@@ -1,5 +1,22 @@
-import { Hono } from "hono";
+import type { Hono } from "hono";
+import { type LazyRoutesLoader } from "./lazy-routes.js";
 import type { VoyantAppConfig, VoyantBindings, VoyantVariables } from "./types.js";
+/** The composed app's Hono env (bindings + framework request variables). */
+type MountEnv<TBindings extends VoyantBindings> = {
+    Bindings: TBindings;
+    Variables: VoyantVariables;
+};
+/**
+ * A lazy route family recorded at mount time so a build-time OpenAPI generator
+ * can eager-load it and merge its `.openapi()` operations (voyant#2114). Mirrors
+ * `LazyMount` in `./openapi.ts` (kept structurally identical, but declared here
+ * to avoid pulling the build-time-only openapi module into the runtime path).
+ */
+export interface LazyMount {
+    /** Absolute surface mount prefix, or `"/"` for absolute `lazyRoutes`. */
+    prefix: string;
+    load: LazyRoutesLoader;
+}
 /**
  * App handle returned alongside the Hono instance. Carries `ready()` for
  * headless / sibling-process deployments that need to fire the lazy
@@ -35,6 +52,13 @@ export interface VoyantAppExtensions<TBindings = unknown> {
      *     await withDbFromEnv(env, (db) => drainOutbox(db, app.eventBus))
      */
     eventBus: import("@voyant-travel/core").EventBus;
+    /**
+     * Lazy route families recorded at mount time (the wildcard dispatch stubs in
+     * `lazy-routes.ts` don't reach the composed `OpenAPIHono` registry). A
+     * build-time OpenAPI generator reads this to eager-load + merge their
+     * `.openapi()` operations via `mergeLazyOpenApiPaths`. Never read at runtime.
+     */
+    lazyMounts: LazyMount[];
 }
 /**
  * Low-level app factory: given an already-resolved `modules`/`extensions` set
@@ -43,8 +67,6 @@ export interface VoyantAppExtensions<TBindings = unknown> {
  * from a manifest + registry + capabilities and delegates here. Use `mountApp`
  * directly only when you have the resolved set in hand (tests, advanced hosts).
  */
-export declare function mountApp<TBindings extends VoyantBindings>(config: VoyantAppConfig<TBindings>): Hono<{
-    Bindings: TBindings;
-    Variables: VoyantVariables;
-}> & VoyantAppExtensions<TBindings>;
+export declare function mountApp<TBindings extends VoyantBindings>(config: VoyantAppConfig<TBindings>): Hono<MountEnv<TBindings>> & VoyantAppExtensions<TBindings>;
+export {};
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAkC3B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAY,eAAe,EAAE,MAAM,YAAY,CAAA;AAyB5F;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,OAAO;IACtD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,qBAAqB,EAAE,QAAQ,CAAA;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,cAAc,EACvD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAke5F"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC,OAAO,EAAE,KAAK,gBAAgB,EAA0C,MAAM,kBAAkB,CAAA;AA0BhG,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAY,eAAe,EAAE,MAAM,YAAY,CAAA;AAI5F,4EAA4E;AAC5E,KAAK,QAAQ,CAAC,SAAS,SAAS,cAAc,IAAI;IAChD,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAA;AAuBD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,OAAO;IACtD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,qBAAqB,EAAE,QAAQ,CAAA;IAChD;;;;;OAKG;IACH,UAAU,EAAE,SAAS,EAAE,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,cAAc,EACvD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAsf5D"}

package/dist/app.js

@@ -1,6 +1,8 @@
+// agent-quality: file-size exception — app.ts is the framework composition root;
+// splitting it is intentional follow-up work, not part of voyant#2114.
+import { OpenAPIHono } from "@hono/zod-openapi";
 import { createContainer, createEventBus, createQueryRunner, } from "@voyant-travel/core";
 import { createOutboxEventStore } from "@voyant-travel/db/outbox";
-import { Hono } from "hono";
 import { assembleAnonymousPaths } from "./anonymous-paths.js";
 import { containerToServiceResolver, makeFrameworkLogger, wireWorkflowRuntime, } from "./app-workflows.js";
 import { mountLazyRoutePaths, mountLazyRoutesAt } from "./lazy-routes.js";
@@ -45,7 +47,13 @@ function buildRateLimitPolicy(config, env, bucket, defaults) {
  * directly only when you have the resolved set in hand (tests, advanced hosts).
  */
 export function mountApp(config) {
-    const app = new Hono();
+    // Composed root is an OpenAPIHono (a drop-in Hono superclass) so module routes
+    // authored with `.openapi()` register here and the spec can be generated via
+    // `@voyant-travel/hono/openapi` at build time. The doc *generator*
+    // (`@asteasolutions/zod-to-openapi` + `openapi3-ts`) is only reachable through
+    // `getOpenAPIDocument`, so it tree-shakes out of the Worker bundle; the
+    // OpenAPIHono registry + validator glue (~35 KB) is the only runtime cost.
+    const app = new OpenAPIHono();
     // Observability sink (RFC #1553) — resolved once and reused by both the
     // outer onError and the forwarded auth sub-app catch point below.
     const reporter = config.reporter ?? noopReporter;
@@ -408,6 +416,13 @@ export function mountApp(config) {
             scopes: c.get("scopes"),
         }));
     }
+    // Lazy route families recorded for build-time OpenAPI merging. The wildcard
+    // dispatch stubs registered by `mountLazyRoutesAt`/`mountLazyRoutePaths` never
+    // reach the composed OpenAPIHono registry, so the spec generator replays these
+    // loaders (see `mergeLazyOpenApiPaths`). Recorded in the same loop that mounts
+    // them so the prefix logic is single-sourced here. Cheap array pushes — no
+    // eager `import()` and no runtime read.
+    const lazyMounts = [];
     // Mount module routes
     for (const mod of allModules) {
         const adminPrefix = `/v1/admin/${mod.module.name}`;
@@ -420,12 +435,15 @@ export function mountApp(config) {
         }
         if (mod.lazyAdminRoutes) {
             mountLazyRoutesAt(app, adminPrefix, mod.lazyAdminRoutes);
+            lazyMounts.push({ prefix: adminPrefix, load: mod.lazyAdminRoutes });
         }
         if (mod.lazyPublicRoutes) {
             mountLazyRoutesAt(app, publicPrefix, mod.lazyPublicRoutes);
+            lazyMounts.push({ prefix: publicPrefix, load: mod.lazyPublicRoutes });
         }
         if (mod.lazyRoutes) {
             mountLazyRoutePaths(app, mod.lazyRoutes.paths, mod.lazyRoutes.load);
+            lazyMounts.push({ prefix: "/", load: mod.lazyRoutes.load });
         }
         if (mod.routes) {
             app.route(`/v1/${mod.module.name}`, mod.routes);
@@ -443,12 +461,15 @@ export function mountApp(config) {
         }
         if (ext.lazyAdminRoutes) {
             mountLazyRoutesAt(app, adminPrefix, ext.lazyAdminRoutes);
+            lazyMounts.push({ prefix: adminPrefix, load: ext.lazyAdminRoutes });
         }
         if (ext.lazyPublicRoutes) {
             mountLazyRoutesAt(app, publicPrefix, ext.lazyPublicRoutes);
+            lazyMounts.push({ prefix: publicPrefix, load: ext.lazyPublicRoutes });
         }
         if (ext.lazyRoutes) {
             mountLazyRoutePaths(app, ext.lazyRoutes.paths, ext.lazyRoutes.load);
+            lazyMounts.push({ prefix: "/", load: ext.lazyRoutes.load });
         }
         if (ext.routes) {
             app.route(`/v1/${ext.extension.module}`, ext.routes);
@@ -468,6 +489,7 @@ export function mountApp(config) {
     // the real `env`.
     const augmented = app;
     augmented.eventBus = eventBus;
+    augmented.lazyMounts = lazyMounts;
     augmented.ready = (bindings) => ensureRuntimeBootstrapped(bindings ?? {});
     return augmented;
 }

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { clientIpKey, consoleLoggerProvider, cors, DEFAULT_IDEMPOTENCY_TTL_MS, d
 export type { HonoExtension, HonoModule } from "./module.js";
 export type { ErrorEvent, Reporter } from "./observability/index.js";
 export { consoleReporter, getRequestId, noopReporter, runWithRequestId, safeCaptureException, } from "./observability/index.js";
+export { openApiValidationHook } from "./openapi-validation.js";
 export type { ExpandedHonoBundles, ExpandedHonoPlugins, HonoBundle, HonoPlugin, } from "./plugin.js";
 export { defineHonoBundle, defineHonoPlugin, expandHonoBundles, expandHonoPlugins, } from "./plugin.js";
 export type { CreatePublicCapabilityOptions, PublicCapabilityCookieOptions, PublicCapabilityPayload, VerifyPublicCapabilityOptions, } from "./public-capability.js";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -7,6 +7,7 @@ export { createLazyRouteHandler, mountLazyRoutePaths, mountLazyRoutesAt, } from
 export { createPathDbSelector } from "./lib/db-selector.js";
 export { clientIpKey, consoleLoggerProvider, cors, DEFAULT_IDEMPOTENCY_TTL_MS, db, enforceRateLimit, errorBoundary, handleApiError, idempotencyKey, isStaffRbacEnforced, LIVE_LIMITS, logger, purgeExpiredIdempotencyKeys, rateLimit, requestId, requireActor, requireAuth, requirePermission, } from "./middleware/index.js";
 export { consoleReporter, getRequestId, noopReporter, runWithRequestId, safeCaptureException, } from "./observability/index.js";
+export { openApiValidationHook } from "./openapi-validation.js";
 export { defineHonoBundle, defineHonoPlugin, expandHonoBundles, expandHonoPlugins, } from "./plugin.js";
 export { createPublicCapabilityToken, extractPublicCapabilityToken, serializePublicCapabilityCookie, verifyPublicCapabilityToken, } from "./public-capability.js";
 export { createDrizzlePublicDocumentDeliveryGrantStore, createPublicDocumentDeliveryGrant, createPublicDocumentDeliveryHonoModule, createPublicDocumentDeliveryRoutes, resolvePublicDocumentDeliveryGrant, revokePublicDocumentDeliveryGrant, } from "./public-document-delivery.js";

package/dist/openapi-validation.d.ts

@@ -0,0 +1,20 @@
+import type { Hook } from "@hono/zod-openapi";
+/**
+ * Shared `OpenAPIHono` `defaultHook` (voyant#2114).
+ *
+ * `@hono/zod-openapi` validates `request` schemas before the handler runs;
+ * without a hook it returns `@hono/zod-validator`'s raw `safeParse` result as a
+ * bare 400, bypassing the framework's `parseQuery`/`parseJsonBody` path and the
+ * shared `{ error, code: "invalid_request", requestId, details }` contract that
+ * clients and the error-boundary rely on. This hook re-routes failures through
+ * the same `RequestValidationError` so `.openapi()` routes stay on-contract.
+ *
+ * Every module that constructs an `OpenAPIHono` must pass it:
+ *
+ *     new OpenAPIHono<Env>({ defaultHook: openApiValidationHook })
+ *
+ * (Validation runs on the instance that owns the route, so a hook on the
+ * composed root app does NOT cover mounted module sub-apps.)
+ */
+export declare const openApiValidationHook: Hook<any, any, any, unknown>;
+//# sourceMappingURL=openapi-validation.d.ts.map

package/dist/openapi-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-validation.d.ts","sourceRoot":"","sources":["../src/openapi-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAG7C;;;;;;;;;;;;;;;;GAgBG;AAIH,eAAO,MAAM,qBAAqB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAI9D,CAAA"}

package/dist/openapi-validation.js

@@ -0,0 +1,26 @@
+import { normalizeValidationError, RequestValidationError } from "./validation.js";
+/**
+ * Shared `OpenAPIHono` `defaultHook` (voyant#2114).
+ *
+ * `@hono/zod-openapi` validates `request` schemas before the handler runs;
+ * without a hook it returns `@hono/zod-validator`'s raw `safeParse` result as a
+ * bare 400, bypassing the framework's `parseQuery`/`parseJsonBody` path and the
+ * shared `{ error, code: "invalid_request", requestId, details }` contract that
+ * clients and the error-boundary rely on. This hook re-routes failures through
+ * the same `RequestValidationError` so `.openapi()` routes stay on-contract.
+ *
+ * Every module that constructs an `OpenAPIHono` must pass it:
+ *
+ *     new OpenAPIHono<Env>({ defaultHook: openApiValidationHook })
+ *
+ * (Validation runs on the instance that owns the route, so a hook on the
+ * composed root app does NOT cover mounted module sub-apps.)
+ */
+// Typed as the library's own `defaultHook` shape (`Hook<any, E, any, any>`) so
+// it stays assignable for every module's specific `OpenAPIHono<Env>`.
+// biome-ignore lint/suspicious/noExplicitAny: matches @hono/zod-openapi's defaultHook signature
+export const openApiValidationHook = (result) => {
+    if (!result.success) {
+        throw normalizeValidationError(result.error) ?? new RequestValidationError("Invalid request");
+    }
+};

package/dist/openapi.d.ts

@@ -0,0 +1,90 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Hono } from "hono";
+import type { LazyRoutesLoader } from "./lazy-routes.js";
+/**
+ * OpenAPI document generation for composed Voyant apps (voyant#2114).
+ *
+ * The app returned by `createApp`/`mountApp` is an `OpenAPIHono` under the hood
+ * (typed as `Hono` for callers), so the helpers here cast to reach
+ * `getOpenAPIDocument`. Only routes authored via `createRoute(...).openapi(...)`
+ * contribute operations — plain routes are absent until migrated.
+ *
+ * Import these from `@voyant-travel/hono/openapi`, never from the package
+ * barrel: `getOpenAPIDocument` pulls in `@asteasolutions/zod-to-openapi`, which
+ * must stay out of the Worker runtime bundle. This module is meant for
+ * build-time generation only.
+ */
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+    /** OpenAPI spec extension fields (`x-*`), matching the doc's `InfoObject`. */
+    [extension: `x-${string}`]: unknown;
+}
+export interface OpenApiServer {
+    url: string;
+    description?: string;
+    [extension: `x-${string}`]: unknown;
+}
+export interface GenerateOpenApiOptions {
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+}
+type AnyApp = Hono<any, any, any>;
+/**
+ * An OpenAPI 3.1 document, as produced by `OpenAPIHono`. Named via the direct
+ * dependency's method type so the inferred type stays portable (TS2883).
+ */
+export type OpenApiDocument = ReturnType<OpenAPIHono["getOpenAPI31Document"]>;
+/**
+ * Generate a single OpenAPI 3.1 document covering every `.openapi()` route
+ * mounted on the composed app, with module base paths already merged in
+ * (honojs/middleware#952).
+ */
+export declare function generateOpenApiDocument(app: AnyApp, options: GenerateOpenApiOptions): OpenApiDocument;
+/**
+ * Voyant's two published API surfaces, keyed by path prefix. Admin routes mount
+ * under `/v1/admin/*` and storefront/public routes under `/v1/public/*`; the
+ * legacy `/v1/*` surface is intentionally excluded from the published docs.
+ */
+export type ApiSurface = "admin" | "storefront";
+/**
+ * Narrow a composed document to a single surface by path prefix, producing the
+ * `framework-admin` / `framework-storefront` documents that replace the
+ * hand-authored specs. Components are carried over verbatim (the generator may
+ * over-include shared component schemas, which is harmless).
+ */
+export declare function selectSurface(doc: OpenApiDocument, surface: ApiSurface): OpenApiDocument;
+/**
+ * A lazy-mounted route family recorded by `mountApp` for build-time spec
+ * merging. `prefix` is the absolute surface mount (`/v1/admin/<name>`,
+ * `/v1/public/...`) for relative-route loaders, or `"/"` for absolute
+ * `lazyRoutes` loaders. `load` is the same loader the runtime dispatcher caches
+ * — it constructs (but does not serve) the sub-app via `import(...)`.
+ */
+export interface LazyMount {
+    prefix: string;
+    load: LazyRoutesLoader;
+}
+/**
+ * Eager-merge lazy route families into a generated base document (voyant#2114).
+ *
+ * Lazy families mount at runtime as wildcard dispatch stubs (see
+ * `lazy-routes.ts`), so their `.openapi()` operations never reach the composed
+ * `OpenAPIHono` registry and are invisible to `generateOpenApiDocument`. This
+ * runs each loader at build time, and for any that return an `OpenAPIHono`,
+ * re-mounts it into a throwaway `OpenAPIHono` at its real prefix — reusing the
+ * exact prefix-merge semantics `OpenAPIHono.route(...)` applies to eager mounts
+ * — then shallow-merges the resulting `paths` + `components.*` into `base`.
+ *
+ * Plain `Hono` sub-apps (no `.openapi()` routes) carry no registry and are
+ * skipped without error. A loader that throws is skipped with a warning so one
+ * bad family can't break generation. `base` wins on path/component collisions
+ * (which shouldn't happen given distinct prefixes), with a dev-time warning.
+ *
+ * Build-time only — same module-level constraint as the rest of this file
+ * (`@asteasolutions/zod-to-openapi` stays out of the Worker bundle).
+ */
+export declare function mergeLazyOpenApiPaths(base: OpenApiDocument, mounts: readonly LazyMount[], options: GenerateOpenApiOptions): Promise<OpenApiDocument>;
+export {};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAC1B;AAGD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEjC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CASjB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,YAAY,CAAA;AAO/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,GAAG,eAAe,CAMxF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CA8D1B"}

package/dist/openapi.js

@@ -0,0 +1,114 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+/**
+ * Generate a single OpenAPI 3.1 document covering every `.openapi()` route
+ * mounted on the composed app, with module base paths already merged in
+ * (honojs/middleware#952).
+ */
+export function generateOpenApiDocument(app, options) {
+    // The composed app is an `OpenAPIHono` (built in `mountApp`) presented to
+    // callers as `Hono`; this build-time seam narrows it back to read the doc.
+    const oapi = app;
+    return oapi.getOpenAPI31Document({
+        openapi: "3.1.0",
+        info: options.info,
+        ...(options.servers ? { servers: options.servers } : {}),
+    });
+}
+const SURFACE_PREFIX = {
+    admin: "/v1/admin",
+    storefront: "/v1/public",
+};
+/**
+ * Narrow a composed document to a single surface by path prefix, producing the
+ * `framework-admin` / `framework-storefront` documents that replace the
+ * hand-authored specs. Components are carried over verbatim (the generator may
+ * over-include shared component schemas, which is harmless).
+ */
+export function selectSurface(doc, surface) {
+    const prefix = SURFACE_PREFIX[surface];
+    const paths = Object.fromEntries(Object.entries(doc.paths ?? {}).filter(([path]) => path.startsWith(prefix)));
+    return { ...doc, paths };
+}
+/** Detect an `OpenAPIHono` sub-app (carries the `.openapi()` route registry). */
+function isOpenApiHono(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.getOpenAPI31Document === "function" &&
+        "openAPIRegistry" in value);
+}
+/**
+ * Eager-merge lazy route families into a generated base document (voyant#2114).
+ *
+ * Lazy families mount at runtime as wildcard dispatch stubs (see
+ * `lazy-routes.ts`), so their `.openapi()` operations never reach the composed
+ * `OpenAPIHono` registry and are invisible to `generateOpenApiDocument`. This
+ * runs each loader at build time, and for any that return an `OpenAPIHono`,
+ * re-mounts it into a throwaway `OpenAPIHono` at its real prefix — reusing the
+ * exact prefix-merge semantics `OpenAPIHono.route(...)` applies to eager mounts
+ * — then shallow-merges the resulting `paths` + `components.*` into `base`.
+ *
+ * Plain `Hono` sub-apps (no `.openapi()` routes) carry no registry and are
+ * skipped without error. A loader that throws is skipped with a warning so one
+ * bad family can't break generation. `base` wins on path/component collisions
+ * (which shouldn't happen given distinct prefixes), with a dev-time warning.
+ *
+ * Build-time only — same module-level constraint as the rest of this file
+ * (`@asteasolutions/zod-to-openapi` stays out of the Worker bundle).
+ */
+export async function mergeLazyOpenApiPaths(base, mounts, options) {
+    const throwaway = new OpenAPIHono();
+    let mergedAny = false;
+    for (const { prefix, load } of mounts) {
+        let subApp;
+        try {
+            subApp = await load();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[voyant] openapi: lazy loader for "${prefix}" failed, skipping: ${message}`);
+            continue;
+        }
+        if (!isOpenApiHono(subApp)) {
+            // Plain Hono (or anything without the registry) contributes no docs.
+            continue;
+        }
+        // `route("/", subApp)` reproduces what an absolute-path (`lazyRoutes`)
+        // family does at runtime; a relative-surface loader merges at its prefix.
+        throwaway.route(prefix === "/" ? "/" : prefix, subApp);
+        mergedAny = true;
+    }
+    if (!mergedAny)
+        return base;
+    const lazyDoc = throwaway.getOpenAPI31Document({
+        openapi: "3.1.0",
+        info: options.info,
+        ...(options.servers ? { servers: options.servers } : {}),
+    });
+    const paths = { ...(base.paths ?? {}) };
+    for (const [path, item] of Object.entries(lazyDoc.paths ?? {})) {
+        if (path in paths) {
+            console.warn(`[voyant] openapi: lazy path "${path}" collides with an eager route; keeping eager.`);
+            continue;
+        }
+        paths[path] = item;
+    }
+    const merged = { ...base, paths };
+    const lazyComponents = lazyDoc.components;
+    if (lazyComponents) {
+        const baseComponents = (base.components ?? {});
+        const mergedComponents = {};
+        const groups = new Set([...Object.keys(baseComponents), ...Object.keys(lazyComponents)]);
+        for (const group of groups) {
+            const baseGroup = (baseComponents[group] ?? {});
+            const lazyGroup = lazyComponents[group] ?? {};
+            const combined = { ...lazyGroup };
+            for (const [key, value] of Object.entries(baseGroup)) {
+                combined[key] = value; // base wins
+            }
+            mergedComponents[group] = combined;
+        }
+        ;
+        merged.components = mergedComponents;
+    }
+    return merged;
+}

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,KAAK,CAAA;AAI5C,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAGxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAClC;CAQJ;AAED,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQ/D;AAED,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,SAAiB;CAOrC;AAED,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,SAAc;CAOlC;AAqBD,wBAAsB,aAAa,CAAC,CAAC,EACnC,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACxF,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GACA,OAAO,CAAC,CAAC,CAAC,CAcZ;AAkBD,wBAAgB,UAAU,CAAC,CAAC,EAC1B,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,CAAC,CAMH;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAUjF"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,KAAK,CAAA;AAI5C,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAGxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAClC;CAQJ;AAED,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQ/D;AAED,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,SAAiB;CAOrC;AAED,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,SAAc;CAOlC;AAqBD,wBAAsB,aAAa,CAAC,CAAC,EACnC,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACxF,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GACA,OAAO,CAAC,CAAC,CAAC,CAcZ;AAkBD,wBAAgB,UAAU,CAAC,CAAC,EAC1B,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,CAAC,CAMH;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAsBjF"}

package/dist/validation.js

@@ -1,3 +1,4 @@
+import { HTTPException } from "hono/http-exception";
 import { ZodError } from "zod";
 import { DEFAULT_REQUEST_BODY_LIMIT_BYTES } from "./middleware/body-size.js";
 export class ApiHttpError extends Error {
@@ -102,5 +103,16 @@ export function normalizeValidationError(error) {
     if (error instanceof ZodError) {
         return toValidationError(error);
     }
+    if (error instanceof HTTPException) {
+        // Hono's request validators throw HTTPException before our validation hook
+        // runs — most notably HTTPException(400, "Malformed JSON in request body")
+        // from the JSON body parser on `.openapi()` routes. Map it onto the
+        // framework error contract so bad client input is a structured 4xx, not a
+        // 500 (voyant#2114).
+        return new ApiHttpError(error.message, {
+            status: error.status,
+            code: error.status === 400 ? "invalid_request" : undefined,
+        });
+    }
     return undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/hono",
-  "version": "0.116.2",
+  "version": "0.117.1",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -14,6 +14,11 @@
       "import": "./dist/app.js",
       "default": "./dist/app.js"
     },
+    "./openapi": {
+      "types": "./dist/openapi.d.ts",
+      "import": "./dist/openapi.js",
+      "default": "./dist/openapi.js"
+    },
     "./module": {
       "types": "./dist/module.d.ts",
       "import": "./dist/module.js",
@@ -126,6 +131,7 @@
     }
   },
   "dependencies": {
+    "@hono/zod-openapi": "^1.4.0",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
@@ -134,14 +140,14 @@
     "@voyant-travel/storage": "^0.105.0",
     "@voyant-travel/types": "^0.106.0",
     "@voyant-travel/utils": "^0.105.4",
-    "@voyant-travel/workflows": "^0.111.8"
+    "@voyant-travel/workflows": "^0.111.9"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260426.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
-    "@voyant-travel/voyant-typescript-config": "^0.1.0",
-    "@voyant-travel/workflows-orchestrator": "^0.111.8"
+    "@voyant-travel/workflows-orchestrator": "^0.111.9",
+    "@voyant-travel/voyant-typescript-config": "^0.1.0"
   },
   "files": [
     "dist"