@veloxts/router 0.7.8 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @veloxts/router
 
+## 0.8.0
+
+### Minor Changes
+
+- feat(router): new simplified procedure builder
+
+### Patch Changes
+
+- Updated dependencies
+  - @veloxts/core@0.8.0
+  - @veloxts/validation@0.8.0
+
+## 0.7.9
+
+### Patch Changes
+
+- feat(router): swagger auto-discovery of module collections
+- Updated dependencies
+  - @veloxts/core@0.7.9
+  - @veloxts/validation@0.7.9
+
 ## 0.7.8
 
 ### Patch Changes

package/GUIDE.md

@@ -28,11 +28,9 @@ export const userProcedures = procedures('users', {
 ## Procedure API
 
 - `.input(schema)` - Validate input with Zod
-- `.output(schema)` - Validate output with Zod
-- `.expose(schema)` - Context-dependent output with resource schema
+- `.output(schema)` - Validate output with Zod schema or tagged resource view
 - `.use(middleware)` - Add middleware
 - `.guard(guard)` - Add authorization guard
-- `.guardNarrow(guard)` - Add guard with TypeScript type narrowing
 - `.rest({ method, path })` - Override REST path
 - `.query(handler)` - Finalize as read operation
 - `.mutation(handler)` - Finalize as write operation
@@ -405,7 +403,7 @@ console.table(routes);
 
 ## Resource API (Context-Dependent Outputs)
 
-The Resource API provides context-dependent output types using phantom types. Pass a resource schema to `.output()` instead of a Zod schema to define field visibility per access level.
+The Resource API provides context-dependent output types using phantom types. Pass a tagged resource view to `.output()` instead of a plain Zod schema to define field visibility per access level.
 
 ### Defining a Resource Schema
 
@@ -423,28 +421,27 @@ const UserSchema = resourceSchema()
   .build();
 ```
 
-### Automatic Projection (Simple Cases)
+### Automatic Projection with `.output()` and Guards
 
-The most elegant approach is to chain `.expose()` with a narrowing guard. The procedure executor automatically projects fields based on the guard's access level:
+The most elegant approach is to chain `.guard()` with `.output()` using a tagged resource view. The procedure builder uses the guard's access level to determine which fields to include:
 
 ```typescript
-import { authenticatedNarrow, adminNarrow } from '@veloxts/auth';
+import { authenticated, hasRole } from '@veloxts/auth';
 
 export const userProcedures = procedures('users', {
-  // Authenticated endpoint - auto-projects { id, name, email, createdAt }
+  // Authenticated endpoint - projects { id, name, email, createdAt }
   getProfile: procedure()
-    .guardNarrow(authenticatedNarrow)
-    .expose(UserSchema)
+    .guard(authenticated)
+    .output(UserSchema.authenticated)
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
-      // Just return the full data - projection is automatic!
       return ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
     }),
 
-  // Admin endpoint - auto-projects all fields
+  // Admin endpoint - projects all fields
   getFullProfile: procedure()
-    .guardNarrow(adminNarrow)
-    .expose(UserSchema)
+    .guard(hasRole('admin'))
+    .output(UserSchema.admin)
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
       return ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
@@ -454,14 +451,13 @@ export const userProcedures = procedures('users', {
 
 **How it works:**
 
-1. The `guardNarrow()` method accepts guards with an `accessLevel` property (`'public'`, `'authenticated'`, or `'admin'`)
-2. After the guard passes, the procedure executor tracks the highest access level
-3. When the handler returns, the executor automatically projects the result using the resource schema
-4. No manual `.forX()` calls needed - the output type is inferred at compile time
+1. The `.output()` method accepts both plain Zod schemas and tagged resource views (e.g., `UserSchema.authenticated`)
+2. When a tagged view is passed, the procedure executor automatically projects the handler's return value
+3. The output type is inferred at compile time from the tagged view
 
 **Benefits:**
 - Clean, declarative code - no projection logic in handlers
-- Type-safe - return types are inferred from guard + schema
+- Type-safe - return types are inferred from the tagged view
 - Less boilerplate - handlers just return data
 - Consistent - impossible to forget projection
 
@@ -516,10 +512,10 @@ export const userProcedures = procedures('users', {
 For arrays of items, use `resourceCollection()`:
 
 ```typescript
-// Automatic projection (simple cases)
+// Automatic projection with .output()
 const listUsers = procedure()
-  .guardNarrow(authenticatedNarrow)
-  .expose(UserSchema)
+  .guard(authenticated)
+  .output(UserSchema.authenticated)
   .query(async ({ ctx }) => {
     return ctx.db.user.findMany({ take: 50 });
   });
@@ -539,7 +535,7 @@ For manual projection with dynamic access level, use `.for(ctx)`:
 
 ```typescript
 const getUser = procedure()
-  .guardNarrow(authenticatedNarrow)
+  .guard(authenticated)
   .input(z.object({ id: z.string().uuid() }))
   .query(async ({ input, ctx }) => {
     const user = await ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
@@ -562,10 +558,10 @@ const getUser = procedure()
 The Resource API provides compile-time type safety:
 
 ```typescript
-// Automatic projection - type inferred from guard
+// Automatic projection - type inferred from tagged view
 const getProfile = procedure()
-  .guardNarrow(authenticatedNarrow)
-  .expose(UserSchema)
+  .guard(authenticated)
+  .output(UserSchema.authenticated)
   .query(async ({ ctx }) => {
     return ctx.db.user.findFirst();
   });
@@ -586,7 +582,7 @@ const adminResult = resource(user, UserSchema.admin);
 
 | Scenario | Approach |
 |----------|----------|
-| Guard determines access level | **Automatic** (`.guardNarrow().output()`) |
+| Guard determines access level | **Automatic** (`.guard().output(Schema.level)`) |
 | Public endpoints (no guard) | Tagged view (`UserSchema.public`) |
 | Conditional/dynamic projection | Tagged view or `.for(ctx)` in handler |
 | Simple, declarative code | **Automatic** |
@@ -603,43 +599,29 @@ const getUser = procedure()
   .query(handler);
 ```
 
-## Guard Type Narrowing (Experimental)
+## Guard Type Narrowing
 
-When using guards like `authenticated`, TypeScript doesn't know that `ctx.user` is guaranteed non-null after the guard passes. Use `guardNarrow()` to narrow the context type:
+Guards like `authenticated` and `hasRole()` both enforce authorization and narrow the context type. After a guard passes, TypeScript knows `ctx.user` is non-null:
 
 ```typescript
-import { authenticatedNarrow, hasRoleNarrow } from '@veloxts/auth';
+import { authenticated, hasRole } from '@veloxts/auth';
 
 // ctx.user is guaranteed non-null after guard passes
 const getProfile = procedure()
-  .guardNarrow(authenticatedNarrow)
+  .guard(authenticated)
   .query(({ ctx }) => {
     return { email: ctx.user.email }; // No null check needed!
   });
 
-// Chain multiple narrowing guards
+// Chain multiple guards
 const adminAction = procedure()
-  .guardNarrow(authenticatedNarrow)
-  .guardNarrow(hasRoleNarrow('admin'))
+  .guard(authenticated)
+  .guard(hasRole('admin'))
   .mutation(({ ctx }) => {
     // ctx.user is non-null with roles
   });
 ```
 
-**Note**: This API is experimental. The current stable alternative is to use middleware for context extension:
-
-```typescript
-const getProfile = procedure()
-  .guard(authenticated)
-  .use(async ({ ctx, next }) => {
-    if (!ctx.user) throw new Error('Unreachable');
-    return next({ ctx: { user: ctx.user } });
-  })
-  .query(({ ctx }) => {
-    // ctx.user is non-null via middleware
-  });
-```
-
 ## Schema Browser-Safety
 
 When building full-stack apps, schemas may be imported on both server and client. Avoid importing server-only dependencies in schema files:

package/README.md

@@ -1,6 +1,6 @@
 # @veloxts/router
 
-> **Early Access (v0.7.x)**
+> **Early Access (v0.8.x)**
 
 Procedure-based routing for VeloxTS Framework - provides hybrid tRPC and REST adapters with naming convention-based HTTP method inference. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 

package/dist/index.d.ts

@@ -46,13 +46,13 @@ export { GuardError, isGuardError } from './errors.js';
 export type { DefineProceduresOptions, } from './procedure/builder.js';
 export { defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, } from './procedure/builder.js';
 export { createProcedure, typedProcedure } from './procedure/factory.js';
-export type { BuilderRuntimeState, InferProcedures, InferSchemaOutput, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidSchema, } from './procedure/types.js';
+export type { BuilderRuntimeState, InferOutputSchema, InferProcedures, InferSchemaOutput, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidOutputSchema, ValidSchema, } from './procedure/types.js';
 export type { RouterResult } from './router-utils.js';
 export { createRouter, toRouter } from './router-utils.js';
 export type { NamingWarning, NamingWarningType, WarningConfig, WarningOption } from './warnings.js';
 export { analyzeNamingConvention, isDevelopment, normalizeWarningOption } from './warnings.js';
-export type { ExtractRoutesType, GenerateRestRoutesOptions, RestAdapterOptions, RestMapping, RestRoute, RouteMap, } from './rest/index.js';
-export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
+export type { ExtractRoutesType, GenerateRestRoutesOptions, RegisteredCollection, RestAdapterOptions, RestMapping, RestRoute, RouteMap, } from './rest/index.js';
+export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, clearCollectionRegistry, extractRoutes, followsNamingConvention, generateRestRoutes, getRegisteredCollections, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
 export type { AnyRouter, CollectionsToRouterRecord, ExtractNamespace, ExtractProcedures, InferRouterFromCollections, MapProcedureRecordToTRPC, MapProcedureToTRPC, TRPCInstance, TRPCPluginOptions, TRPCRouter, } from './trpc/index.js';
 export { appRouter, buildTRPCRouter, createTRPCContextFactory, registerTRPCPlugin, trpc, veloxErrorToTRPCError, } from './trpc/index.js';
 export type { RpcOptions, RpcResult } from './rpc.js';
@@ -82,7 +82,7 @@ export { serve } from './expose.js';
  * ```
  */
 export type { BuildParametersOptions, BuildParametersResult, GuardMappingOptions, JSONSchema, OpenAPIComponents, OpenAPIContact, OpenAPIEncoding, OpenAPIExample, OpenAPIExternalDocs, OpenAPIGeneratorOptions, OpenAPIHeader, OpenAPIHttpMethod, OpenAPIInfo, OpenAPILicense, OpenAPILink, OpenAPIMediaType, OpenAPIOAuthFlow, OpenAPIOAuthFlows, OpenAPIOperation, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPISpec, OpenAPITag, ParameterIn, QueryParamExtractionOptions, RouteInfo, SchemaConversionOptions, SecuritySchemeType, SwaggerUIConfig, SwaggerUIHtmlOptions, SwaggerUIPluginOptions, } from './openapi/index.js';
-export { buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, createSecurityRequirement, createStringSchema, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, generateOpenApiSpec, generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
+export { buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, createSecurityRequirement, createStringSchema, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, generateOpenApiSpec, generateOpenApiSpecFromRegistry, generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
 export type { AccessLevel, AccessLevelConfig, ADMIN, AdminOutput, AdminTaggedContext, ANONYMOUS, AnonymousOutput, AnonymousTaggedContext, AnyResourceOutput, AUTHENTICATED, AuthenticatedOutput, AuthenticatedTaggedContext, BuilderField, ContextTag, CustomResourceSchemaWithViews, CustomSchemaBuilder, ExtractTag, FilterFieldsByLevel, HasTag, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, IsVisibleToTag, LevelToTag, OutputForLevel, OutputForTag, PUBLIC, PublicOutput, PublicTaggedContext, RelationField, ResourceField, ResourceSchema, ResourceSchemaWithViews, RuntimeField, TaggedContext, TagToLevel, VisibilityLevel, WithTag, } from './resource/index.js';
 /**
  * Resource API for context-dependent output types using phantom types.
@@ -114,4 +114,4 @@ export type { AccessLevel, AccessLevelConfig, ADMIN, AdminOutput, AdminTaggedCon
  * });
  * ```
  */
-export { defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';
+export { defaultAccess, defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';

package/dist/index.js

@@ -58,7 +58,7 @@ defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection,
 export { createProcedure, typedProcedure } from './procedure/factory.js';
 export { createRouter, toRouter } from './router-utils.js';
 export { analyzeNamingConvention, isDevelopment, normalizeWarningOption } from './warnings.js';
-export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
+export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, clearCollectionRegistry, extractRoutes, followsNamingConvention, generateRestRoutes, getRegisteredCollections, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
 export { 
 // tRPC utilities
 appRouter, buildTRPCRouter, createTRPCContextFactory, registerTRPCPlugin, trpc, veloxErrorToTRPCError, } from './trpc/index.js';
@@ -73,7 +73,7 @@ createSecurityRequirement,
 // Schema converter
 createStringSchema, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, 
 // Generator
-generateOpenApiSpec, 
+generateOpenApiSpec, generateOpenApiSpecFromRegistry, 
 // HTML Generator
 generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, 
 // Plugin
@@ -110,7 +110,7 @@ swaggerPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/ind
  */
 export { 
 // Access level configuration
-defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, 
+defaultAccess, defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, 
 // Visibility
 isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, 
 // Resource instances

package/dist/openapi/generator.d.ts

@@ -5,11 +5,15 @@
  *
  * @module @veloxts/router/openapi/generator
  */
+import type { RegisteredCollection } from '../rest/registry.js';
 import type { ProcedureCollection } from '../types.js';
 import type { OpenAPIGeneratorOptions, OpenAPISpec } from './types.js';
 /**
  * Generates an OpenAPI 3.0.3 specification from procedure collections
  *
+ * All collections share the same prefix from `options.prefix` (default '/api').
+ * For collections with different prefixes, use `generateOpenApiSpecFromRegistry()`.
+ *
  * @param collections - Array of procedure collections to document
  * @param options - Generator options
  * @returns Complete OpenAPI specification
@@ -30,6 +34,27 @@ import type { OpenAPIGeneratorOptions, OpenAPISpec } from './types.js';
  * ```
  */
 export declare function generateOpenApiSpec(collections: ProcedureCollection[], options: OpenAPIGeneratorOptions): OpenAPISpec;
+/**
+ * Generates an OpenAPI 3.0.3 specification from registered collections
+ *
+ * Each entry carries its own prefix, allowing collections registered under
+ * different Fastify prefixes (e.g., `/api` and `/loterie`) to produce
+ * correct paths in a single spec.
+ *
+ * @param entries - Registered collections with per-entry prefixes
+ * @param options - Generator options (prefix field is ignored — per-entry prefix is used)
+ * @returns Complete OpenAPI specification
+ *
+ * @example
+ * ```typescript
+ * import { generateOpenApiSpecFromRegistry, getRegisteredCollections } from '@veloxts/router';
+ *
+ * const spec = generateOpenApiSpecFromRegistry(getRegisteredCollections(), {
+ *   info: { title: 'My API', version: '1.0.0' },
+ * });
+ * ```
+ */
+export declare function generateOpenApiSpecFromRegistry(entries: readonly RegisteredCollection[], options: OpenAPIGeneratorOptions): OpenAPISpec;
 /**
  * Gets route summary information for debugging/logging
  *

package/dist/openapi/generator.js

@@ -7,7 +7,7 @@
  */
 import { generateRestRoutes } from '../rest/adapter.js';
 import { buildParameters, convertToOpenAPIPath, joinPaths } from './path-extractor.js';
-import { removeSchemaProperties, resourceSchemaToJsonSchema, zodSchemaToJsonSchema, } from './schema-converter.js';
+import { removeSchemaProperties, resourceSchemaToJsonSchema, resourceSchemaToJsonSchemaForBranching, zodSchemaToJsonSchema, } from './schema-converter.js';
 import { extractUsedSecuritySchemes, filterUsedSecuritySchemes, guardsToSecurity, mergeSecuritySchemes, } from './security-mapper.js';
 // ============================================================================
 // Main Generator
@@ -15,6 +15,9 @@ import { extractUsedSecuritySchemes, filterUsedSecuritySchemes, guardsToSecurity
 /**
  * Generates an OpenAPI 3.0.3 specification from procedure collections
  *
+ * All collections share the same prefix from `options.prefix` (default '/api').
+ * For collections with different prefixes, use `generateOpenApiSpecFromRegistry()`.
+ *
  * @param collections - Array of procedure collections to document
  * @param options - Generator options
  * @returns Complete OpenAPI specification
@@ -36,20 +39,53 @@ import { extractUsedSecuritySchemes, filterUsedSecuritySchemes, guardsToSecurity
  */
 export function generateOpenApiSpec(collections, options) {
     const prefix = options.prefix ?? '/api';
+    // Convert to RegisteredCollection entries with the shared prefix
+    const entries = collections.map((collection) => ({
+        collection,
+        prefix,
+    }));
+    return generateOpenApiSpecFromRegistry(entries, options);
+}
+/**
+ * Generates an OpenAPI 3.0.3 specification from registered collections
+ *
+ * Each entry carries its own prefix, allowing collections registered under
+ * different Fastify prefixes (e.g., `/api` and `/loterie`) to produce
+ * correct paths in a single spec.
+ *
+ * @param entries - Registered collections with per-entry prefixes
+ * @param options - Generator options (prefix field is ignored — per-entry prefix is used)
+ * @returns Complete OpenAPI specification
+ *
+ * @example
+ * ```typescript
+ * import { generateOpenApiSpecFromRegistry, getRegisteredCollections } from '@veloxts/router';
+ *
+ * const spec = generateOpenApiSpecFromRegistry(getRegisteredCollections(), {
+ *   info: { title: 'My API', version: '1.0.0' },
+ * });
+ * ```
+ */
+export function generateOpenApiSpecFromRegistry(entries, options) {
     const paths = {};
     const tags = [];
     const allGuards = [];
-    // Process each collection
-    for (const collection of collections) {
+    const seenTagNames = new Set();
+    // Process each registered entry
+    for (const entry of entries) {
+        const { collection, prefix } = entry;
         const routes = generateRestRoutes(collection);
-        // Add tag for this namespace
-        tags.push({
-            name: collection.namespace,
-            description: options.tagDescriptions?.[collection.namespace],
-        });
+        // Add tag for this namespace (deduplicate across entries)
+        if (!seenTagNames.has(collection.namespace)) {
+            seenTagNames.add(collection.namespace);
+            tags.push({
+                name: collection.namespace,
+                description: options.tagDescriptions?.[collection.namespace],
+            });
+        }
         // Process each route
         for (const route of routes) {
-            // Build full path with prefix
+            // Build full path with this entry's prefix
             const fullPath = joinPaths(prefix, route.path);
             const openApiPath = convertToOpenAPIPath(fullPath);
             // Initialize path item if not exists
@@ -114,6 +150,10 @@ function generateOperation(route, namespace, options) {
     if (procedure.outputSchema) {
         outputSchema = zodSchemaToJsonSchema(procedure.outputSchema);
     }
+    else if (procedure._handlerMap && procedure._resourceSchema) {
+        // Level 3: branched procedure — include all fields, non-public fields optional
+        outputSchema = resourceSchemaToJsonSchemaForBranching(procedure._resourceSchema);
+    }
     else if (procedure._resourceSchema) {
         const level = procedure._resourceLevel ?? 'public';
         outputSchema = resourceSchemaToJsonSchema(procedure._resourceSchema, level);

package/dist/openapi/index.d.ts

@@ -28,7 +28,7 @@
  * });
  * ```
  */
-export { generateOpenApiSpec, getOpenApiRouteSummary, validateOpenApiSpec, } from './generator.js';
+export { generateOpenApiSpec, generateOpenApiSpecFromRegistry, getOpenApiRouteSummary, validateOpenApiSpec, } from './generator.js';
 export { getOpenApiSpec, swaggerPlugin, } from './plugin.js';
 export { DEFAULT_UI_CONFIG, escapeHtml, generateSwaggerUIHtml, SWAGGER_UI_CDN, type SwaggerUIHtmlOptions, } from './html-generator.js';
 export { createStringSchema, extractSchemaProperties, mergeSchemas, removeSchemaProperties, type SchemaConversionOptions, schemaHasProperties, zodSchemaToJsonSchema, } from './schema-converter.js';

package/dist/openapi/index.js

@@ -31,7 +31,7 @@
 // ============================================================================
 // Generator
 // ============================================================================
-export { generateOpenApiSpec, getOpenApiRouteSummary, validateOpenApiSpec, } from './generator.js';
+export { generateOpenApiSpec, generateOpenApiSpecFromRegistry, getOpenApiRouteSummary, validateOpenApiSpec, } from './generator.js';
 // ============================================================================
 // Plugin
 // ============================================================================

package/dist/openapi/plugin.d.ts

@@ -12,22 +12,27 @@ import type { OpenAPISpec, SwaggerUIPluginOptions } from './types.js';
  *
  * Registers routes for serving Swagger UI and the OpenAPI specification.
  *
+ * When `collections` is omitted, the plugin auto-discovers all collections
+ * previously registered via `rest()`, using each collection's effective prefix.
+ *
  * @example
  * ```typescript
  * import { swaggerPlugin } from '@veloxts/router';
  *
+ * // Explicit collections (backward compatible)
  * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures, postProcedures],
  *   openapi: {
- *     info: {
- *       title: 'My API',
- *       version: '1.0.0',
- *       description: 'A VeloxTS-powered API',
- *     },
+ *     info: { title: 'My API', version: '1.0.0' },
  *     servers: [{ url: 'http://localhost:3030' }],
  *   },
  * });
+ *
+ * // Auto-discovery — no collections needed
+ * app.register(swaggerPlugin, {
+ *   openapi: { info: { title: 'My API', version: '1.0.0' } },
+ * });
  * ```
  */
 export declare const swaggerPlugin: FastifyPluginAsync<SwaggerUIPluginOptions>;
@@ -35,6 +40,7 @@ export declare const swaggerPlugin: FastifyPluginAsync<SwaggerUIPluginOptions>;
  * Gets the generated OpenAPI specification without registering routes
  *
  * Useful for testing or exporting the spec programmatically.
+ * Supports auto-discovery when `collections` is omitted.
  *
  * @param options - Plugin options
  * @returns Generated OpenAPI specification

package/dist/openapi/plugin.js

@@ -5,9 +5,27 @@
  *
  * @module @veloxts/router/openapi/plugin
  */
-import { generateOpenApiSpec } from './generator.js';
+import { getRegisteredCollections } from '../rest/registry.js';
+import { generateOpenApiSpec, generateOpenApiSpecFromRegistry } from './generator.js';
 import { generateSwaggerUIHtml } from './html-generator.js';
 // ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Build an OpenAPI spec from plugin options.
+ *
+ * - Explicit `collections` → use `generateOpenApiSpec` (single global prefix)
+ * - No collections → auto-discover from the registry (per-entry prefix)
+ */
+function buildSpec(options) {
+    const { collections, openapi } = options;
+    if (collections && collections.length > 0) {
+        return generateOpenApiSpec(collections, openapi);
+    }
+    const registered = getRegisteredCollections();
+    return generateOpenApiSpecFromRegistry(registered, openapi);
+}
+// ============================================================================
 // Fastify Plugin
 // ============================================================================
 /**
@@ -15,30 +33,35 @@ import { generateSwaggerUIHtml } from './html-generator.js';
  *
  * Registers routes for serving Swagger UI and the OpenAPI specification.
  *
+ * When `collections` is omitted, the plugin auto-discovers all collections
+ * previously registered via `rest()`, using each collection's effective prefix.
+ *
  * @example
  * ```typescript
  * import { swaggerPlugin } from '@veloxts/router';
  *
+ * // Explicit collections (backward compatible)
  * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures, postProcedures],
  *   openapi: {
- *     info: {
- *       title: 'My API',
- *       version: '1.0.0',
- *       description: 'A VeloxTS-powered API',
- *     },
+ *     info: { title: 'My API', version: '1.0.0' },
  *     servers: [{ url: 'http://localhost:3030' }],
  *   },
  * });
+ *
+ * // Auto-discovery — no collections needed
+ * app.register(swaggerPlugin, {
+ *   openapi: { info: { title: 'My API', version: '1.0.0' } },
+ * });
  * ```
  */
 export const swaggerPlugin = async (fastify, options) => {
-    const { routePrefix = '/docs', specRoute = `${routePrefix}/openapi.json`, uiConfig = {}, openapi, collections, title = 'API Documentation', favicon, } = options;
+    const { routePrefix = '/docs', specRoute = `${routePrefix}/openapi.json`, uiConfig = {}, title = 'API Documentation', favicon, } = options;
     // Generate the OpenAPI specification
     let spec;
     try {
-        spec = generateOpenApiSpec(collections, openapi);
+        spec = buildSpec(options);
     }
     catch (error) {
         fastify.log.error(error, '[VeloxTS] Failed to generate OpenAPI specification');
@@ -73,6 +96,7 @@ export const swaggerPlugin = async (fastify, options) => {
  * Gets the generated OpenAPI specification without registering routes
  *
  * Useful for testing or exporting the spec programmatically.
+ * Supports auto-discovery when `collections` is omitted.
  *
  * @param options - Plugin options
  * @returns Generated OpenAPI specification
@@ -93,5 +117,5 @@ export const swaggerPlugin = async (fastify, options) => {
  * ```
  */
 export function getOpenApiSpec(options) {
-    return generateOpenApiSpec(options.collections, options.openapi);
+    return buildSpec(options);
 }

package/dist/openapi/schema-converter.d.ts

@@ -113,3 +113,14 @@ export declare function schemaHasProperties(schema: JSONSchema | undefined): boo
  * @returns JSON Schema with only the fields visible at the given level
  */
 export declare function resourceSchemaToJsonSchema(schema: ResourceSchema, level?: string): JSONSchema;
+/**
+ * Converts a resource schema to JSON Schema for Level 3 branched procedures
+ *
+ * Includes ALL fields from the resource schema. Fields visible at the
+ * lowest level (first in the levels array) are marked as required;
+ * higher-level-only fields are optional.
+ *
+ * @param schema - The resource schema (must have _levelConfig for custom levels)
+ * @returns JSON Schema with all fields, non-public fields optional
+ */
+export declare function resourceSchemaToJsonSchemaForBranching(schema: ResourceSchema): JSONSchema;

package/dist/openapi/schema-converter.js

@@ -308,3 +308,50 @@ export function resourceSchemaToJsonSchema(schema, level = 'public') {
         ...(required.length > 0 ? { required } : {}),
     };
 }
+/**
+ * Converts a resource schema to JSON Schema for Level 3 branched procedures
+ *
+ * Includes ALL fields from the resource schema. Fields visible at the
+ * lowest level (first in the levels array) are marked as required;
+ * higher-level-only fields are optional.
+ *
+ * @param schema - The resource schema (must have _levelConfig for custom levels)
+ * @returns JSON Schema with all fields, non-public fields optional
+ */
+export function resourceSchemaToJsonSchemaForBranching(schema) {
+    const properties = {};
+    const required = [];
+    // Determine the lowest (most accessible) level
+    const schemaWithConfig = schema;
+    const lowestLevel = schemaWithConfig._levelConfig?.levels[0] ?? 'public';
+    for (const field of schema.fields) {
+        const runtimeField = field;
+        if (field.nestedSchema) {
+            const nestedJsonSchema = resourceSchemaToJsonSchemaForBranching(field.nestedSchema);
+            if (field.cardinality === 'many') {
+                properties[field.name] = { type: 'array', items: nestedJsonSchema };
+            }
+            else {
+                properties[field.name] = { ...nestedJsonSchema, nullable: true };
+            }
+        }
+        else if (field.schema) {
+            const fieldJsonSchema = zodSchemaToJsonSchema(field.schema);
+            if (fieldJsonSchema) {
+                properties[field.name] = fieldJsonSchema;
+            }
+        }
+        else {
+            properties[field.name] = {};
+        }
+        // Only public/lowest-level fields are required
+        if (isFieldVisibleToLevel(runtimeField, lowestLevel)) {
+            required.push(field.name);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}

package/dist/openapi/types.d.ts

@@ -404,9 +404,12 @@ export interface SwaggerUIPluginOptions {
      */
     openapi: OpenAPIGeneratorOptions;
     /**
-     * Procedure collections to document
+     * Procedure collections to document.
+     *
+     * When omitted, the plugin auto-discovers collections registered via `rest()`
+     * along with their effective prefixes.
      */
-    collections: ProcedureCollection[];
+    collections?: ProcedureCollection[];
     /**
      * Custom page title
      * @default 'API Documentation'