@veloxts/router 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/router
 
+## 0.7.7
+
+### Patch Changes
+
+- refactor(router): rename swaggerUIPlugin → swaggerPlugin, remove redundant exports
+- Updated dependencies
+  - @veloxts/core@0.7.7
+  - @veloxts/validation@0.7.7
+
+## 0.7.6
+
+### Patch Changes
+
+- feat(router): custom access levels for the Resource API + advanced Architectural Patterns
+- Updated dependencies
+  - @veloxts/core@0.7.6
+  - @veloxts/validation@0.7.6
+
 ## 0.7.5
 
 ### Patch Changes

package/GUIDE.md

@@ -28,8 +28,8 @@ export const userProcedures = procedures('users', {
 ## Procedure API
 
 - `.input(schema)` - Validate input with Zod
-- `.output(schema)` - Validate output with Zod (same fields for all users)
-- `.resource(schema)` - Context-dependent output with field visibility
+- `.output(schema)` - Validate output with Zod
+- `.expose(schema)` - Context-dependent output with resource schema
 - `.use(middleware)` - Add middleware
 - `.guard(guard)` - Add authorization guard
 - `.guardNarrow(guard)` - Add guard with TypeScript type narrowing
@@ -198,9 +198,9 @@ fs.writeFileSync('openapi.json', JSON.stringify(spec, null, 2));
 Serve interactive API documentation with Swagger UI:
 
 ```typescript
-import { swaggerUIPlugin } from '@veloxts/router';
+import { swaggerPlugin } from '@veloxts/router';
 
-app.server.register(swaggerUIPlugin, {
+app.server.register(swaggerPlugin, {
   routePrefix: '/docs',
   collections: [userProcedures, postProcedures],
   openapi: {
@@ -215,31 +215,6 @@ app.server.register(swaggerUIPlugin, {
 // - /docs/openapi.json - Raw OpenAPI spec
 ```
 
-### Factory Functions
-
-```typescript
-import { createSwaggerUI, getOpenApiSpec, registerDocs } from '@veloxts/router';
-
-// Create pre-configured plugin
-const docs = createSwaggerUI({
-  collections: [userProcedures],
-  openapi: { info: { title: 'My API', version: '1.0.0' } },
-});
-app.server.register(docs);
-
-// Get spec without registering routes
-const spec = getOpenApiSpec({
-  collections: [userProcedures],
-  openapi: { info: { title: 'My API', version: '1.0.0' } },
-});
-
-// Register docs with one call
-await registerDocs(app.server, {
-  collections: [userProcedures],
-  openapi: { info: { title: 'My API', version: '1.0.0' } },
-});
-```
-
 ### CLI Commands
 
 Generate and serve OpenAPI specs from the command line:
@@ -430,7 +405,7 @@ console.table(routes);
 
 ## Resource API (Context-Dependent Outputs)
 
-The Resource API provides context-dependent output types using phantom types. Unlike `.output()` which returns the same fields to all users, `.resource()` lets you define field visibility per access level.
+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.
 
 ### Defining a Resource Schema
 
@@ -450,7 +425,7 @@ const UserSchema = resourceSchema()
 
 ### Automatic Projection (Simple Cases)
 
-The most elegant approach is to chain `.resource()` with a narrowing guard. The procedure executor automatically projects fields based on the guard's access level:
+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:
 
 ```typescript
 import { authenticatedNarrow, adminNarrow } from '@veloxts/auth';
@@ -459,7 +434,7 @@ export const userProcedures = procedures('users', {
   // Authenticated endpoint - auto-projects { id, name, email, createdAt }
   getProfile: procedure()
     .guardNarrow(authenticatedNarrow)
-    .resource(UserSchema)
+    .expose(UserSchema)
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
       // Just return the full data - projection is automatic!
@@ -469,7 +444,7 @@ export const userProcedures = procedures('users', {
   // Admin endpoint - auto-projects all fields
   getFullProfile: procedure()
     .guardNarrow(adminNarrow)
-    .resource(UserSchema)
+    .expose(UserSchema)
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
       return ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
@@ -544,7 +519,7 @@ For arrays of items, use `resourceCollection()`:
 // Automatic projection (simple cases)
 const listUsers = procedure()
   .guardNarrow(authenticatedNarrow)
-  .resource(UserSchema)
+  .expose(UserSchema)
   .query(async ({ ctx }) => {
     return ctx.db.user.findMany({ take: 50 });
   });
@@ -590,7 +565,7 @@ The Resource API provides compile-time type safety:
 // Automatic projection - type inferred from guard
 const getProfile = procedure()
   .guardNarrow(authenticatedNarrow)
-  .resource(UserSchema)
+  .expose(UserSchema)
   .query(async ({ ctx }) => {
     return ctx.db.user.findFirst();
   });
@@ -611,7 +586,7 @@ const adminResult = resource(user, UserSchema.admin);
 
 | Scenario | Approach |
 |----------|----------|
-| Guard determines access level | **Automatic** (`.guardNarrow().resource()`) |
+| Guard determines access level | **Automatic** (`.guardNarrow().output()`) |
 | Public endpoints (no guard) | Tagged view (`UserSchema.public`) |
 | Conditional/dynamic projection | Tagged view or `.for(ctx)` in handler |
 | Simple, declarative code | **Automatic** |

package/dist/index.d.ts

@@ -39,7 +39,7 @@
  */
 /** Router package version */
 export declare const ROUTER_VERSION: string;
-export type { CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureInput, InferProcedureOutput, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, } from './types.js';
+export type { CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, } from './types.js';
 export { PROCEDURE_METHOD_MAP, } from './types.js';
 export type { GuardErrorResponse, RouterErrorCode } from './errors.js';
 export { GuardError, isGuardError } from './errors.js';
@@ -66,7 +66,7 @@ export { serve } from './expose.js';
  *
  * @example
  * ```typescript
- * import { generateOpenApiSpec, swaggerUIPlugin } from '@veloxts/router';
+ * import { generateOpenApiSpec, swaggerPlugin } from '@veloxts/router';
  *
  * // Generate spec programmatically
  * const spec = generateOpenApiSpec([userProcedures], {
@@ -74,7 +74,7 @@ export { serve } from './expose.js';
  * });
  *
  * // Or serve Swagger UI
- * app.register(swaggerUIPlugin, {
+ * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures],
  *   openapi: { info: { title: 'My API', version: '1.0.0' } },
@@ -82,8 +82,8 @@ 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, createSwaggerUI, 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, registerDocs, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
-export type { AccessLevel, ADMIN, AdminOutput, AdminTaggedContext, ANONYMOUS, AnonymousOutput, AnonymousTaggedContext, AnyResourceOutput, AUTHENTICATED, AuthenticatedOutput, AuthenticatedTaggedContext, BuilderField, ContextTag, ExtractTag, HasTag, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, IsVisibleToTag, OutputForTag, RelationField, ResourceField, ResourceSchema, RuntimeField, TaggedContext, VisibilityLevel, WithTag, } from './resource/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 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.
  *
@@ -109,9 +109,9 @@ export type { AccessLevel, ADMIN, AdminOutput, AdminTaggedContext, ANONYMOUS, An
  *     .input(z.object({ id: z.string() }))
  *     .query(async ({ input, ctx }) => {
  *       const user = await ctx.db.user.findUnique({ where: { id: input.id } });
- *       return resource(user, UserSchema).forAnonymous();
+ *       return resource(user, UserSchema).forPublic();
  *     }),
  * });
  * ```
  */
-export { getAccessibleLevels, getVisibilityForTag, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';
+export { defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';

package/dist/index.js

@@ -71,13 +71,13 @@ buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath,
 // Security mapper
 createSecurityRequirement, 
 // Schema converter
-createStringSchema, 
-// Plugin
-createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, 
+createStringSchema, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, 
 // Generator
 generateOpenApiSpec, 
 // HTML Generator
-generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
+generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, 
+// Plugin
+swaggerPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
 /**
  * Resource API for context-dependent output types using phantom types.
  *
@@ -103,12 +103,14 @@ generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth
  *     .input(z.object({ id: z.string() }))
  *     .query(async ({ input, ctx }) => {
  *       const user = await ctx.db.user.findUnique({ where: { id: input.id } });
- *       return resource(user, UserSchema).forAnonymous();
+ *       return resource(user, UserSchema).forPublic();
  *     }),
  * });
  * ```
  */
-export { getAccessibleLevels, getVisibilityForTag, isResourceSchema, 
+export { 
+// Access level configuration
+defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, 
 // Visibility
 isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, 
 // Resource instances

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, zodSchemaToJsonSchema } from './schema-converter.js';
+import { removeSchemaProperties, resourceSchemaToJsonSchema, zodSchemaToJsonSchema, } from './schema-converter.js';
 import { extractUsedSecuritySchemes, filterUsedSecuritySchemes, guardsToSecurity, mergeSecuritySchemes, } from './security-mapper.js';
 // ============================================================================
 // Main Generator
@@ -110,9 +110,14 @@ function generateOperation(route, namespace, options) {
     const inputSchema = procedure.inputSchema
         ? zodSchemaToJsonSchema(procedure.inputSchema)
         : undefined;
-    const outputSchema = procedure.outputSchema
-        ? zodSchemaToJsonSchema(procedure.outputSchema)
-        : undefined;
+    let outputSchema;
+    if (procedure.outputSchema) {
+        outputSchema = zodSchemaToJsonSchema(procedure.outputSchema);
+    }
+    else if (procedure._resourceSchema) {
+        const level = procedure._resourceLevel ?? 'public';
+        outputSchema = resourceSchemaToJsonSchema(procedure._resourceSchema, level);
+    }
     // Build parameters
     const { pathParams, queryParams, pathParamNames } = buildParameters({
         path,

package/dist/openapi/index.d.ts

@@ -9,8 +9,7 @@
  * ```typescript
  * import {
  *   generateOpenApiSpec,
- *   swaggerUIPlugin,
- *   createSwaggerUI,
+ *   swaggerPlugin,
  * } from '@veloxts/router';
  *
  * // Generate spec programmatically
@@ -20,7 +19,7 @@
  * });
  *
  * // Or register Swagger UI plugin
- * app.register(swaggerUIPlugin, {
+ * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures],
  *   openapi: {
@@ -30,7 +29,7 @@
  * ```
  */
 export { generateOpenApiSpec, getOpenApiRouteSummary, validateOpenApiSpec, } from './generator.js';
-export { createSwaggerUI, getOpenApiSpec, registerDocs, swaggerUIPlugin, } from './plugin.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';
 export { type BuildParametersOptions, type BuildParametersResult, buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, extractPathParamNames, extractQueryParameters, extractResourceFromPath, hasPathParameters, joinPaths, normalizePath, parsePathParameters, type QueryParamExtractionOptions, } from './path-extractor.js';

package/dist/openapi/index.js

@@ -9,8 +9,7 @@
  * ```typescript
  * import {
  *   generateOpenApiSpec,
- *   swaggerUIPlugin,
- *   createSwaggerUI,
+ *   swaggerPlugin,
  * } from '@veloxts/router';
  *
  * // Generate spec programmatically
@@ -20,7 +19,7 @@
  * });
  *
  * // Or register Swagger UI plugin
- * app.register(swaggerUIPlugin, {
+ * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures],
  *   openapi: {
@@ -36,7 +35,7 @@ export { generateOpenApiSpec, getOpenApiRouteSummary, validateOpenApiSpec, } fro
 // ============================================================================
 // Plugin
 // ============================================================================
-export { createSwaggerUI, getOpenApiSpec, registerDocs, swaggerUIPlugin, } from './plugin.js';
+export { getOpenApiSpec, swaggerPlugin, } from './plugin.js';
 // ============================================================================
 // HTML Generator
 // ============================================================================

package/dist/openapi/plugin.d.ts

@@ -14,9 +14,9 @@ import type { OpenAPISpec, SwaggerUIPluginOptions } from './types.js';
  *
  * @example
  * ```typescript
- * import { swaggerUIPlugin } from '@veloxts/router';
+ * import { swaggerPlugin } from '@veloxts/router';
  *
- * app.register(swaggerUIPlugin, {
+ * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures, postProcedures],
  *   openapi: {
@@ -30,51 +30,7 @@ import type { OpenAPISpec, SwaggerUIPluginOptions } from './types.js';
  * });
  * ```
  */
-export declare const swaggerUIPlugin: FastifyPluginAsync<SwaggerUIPluginOptions>;
-/**
- * Creates a Swagger UI plugin with pre-configured options
- *
- * @param options - Plugin options
- * @returns Configured plugin
- *
- * @example
- * ```typescript
- * import { createSwaggerUI } from '@veloxts/router';
- *
- * const docs = createSwaggerUI({
- *   collections: [userProcedures],
- *   openapi: {
- *     info: { title: 'My API', version: '1.0.0' },
- *   },
- * });
- *
- * app.register(docs);
- * ```
- */
-export declare function createSwaggerUI(options: SwaggerUIPluginOptions): FastifyPluginAsync<SwaggerUIPluginOptions>;
-/**
- * Registers multiple procedure collections with Swagger UI
- *
- * Convenience function that sets up both REST routes and documentation.
- *
- * @param fastify - Fastify instance
- * @param options - Documentation options
- *
- * @example
- * ```typescript
- * import { registerDocs } from '@veloxts/router';
- *
- * await registerDocs(app, {
- *   collections: [userProcedures, postProcedures],
- *   openapi: {
- *     info: { title: 'My API', version: '1.0.0' },
- *   },
- * });
- * ```
- */
-export declare function registerDocs(fastify: {
-    register: (plugin: FastifyPluginAsync<SwaggerUIPluginOptions>, options: SwaggerUIPluginOptions) => Promise<void>;
-}, options: SwaggerUIPluginOptions): Promise<void>;
+export declare const swaggerPlugin: FastifyPluginAsync<SwaggerUIPluginOptions>;
 /**
  * Gets the generated OpenAPI specification without registering routes
  *

package/dist/openapi/plugin.js

@@ -17,9 +17,9 @@ import { generateSwaggerUIHtml } from './html-generator.js';
  *
  * @example
  * ```typescript
- * import { swaggerUIPlugin } from '@veloxts/router';
+ * import { swaggerPlugin } from '@veloxts/router';
  *
- * app.register(swaggerUIPlugin, {
+ * app.register(swaggerPlugin, {
  *   routePrefix: '/docs',
  *   collections: [userProcedures, postProcedures],
  *   openapi: {
@@ -33,7 +33,7 @@ import { generateSwaggerUIHtml } from './html-generator.js';
  * });
  * ```
  */
-export const swaggerUIPlugin = async (fastify, options) => {
+export const swaggerPlugin = async (fastify, options) => {
     const { routePrefix = '/docs', specRoute = `${routePrefix}/openapi.json`, uiConfig = {}, openapi, collections, title = 'API Documentation', favicon, } = options;
     // Generate the OpenAPI specification
     let spec;
@@ -69,54 +69,6 @@ export const swaggerUIPlugin = async (fastify, options) => {
 // ============================================================================
 // Utility Functions
 // ============================================================================
-/**
- * Creates a Swagger UI plugin with pre-configured options
- *
- * @param options - Plugin options
- * @returns Configured plugin
- *
- * @example
- * ```typescript
- * import { createSwaggerUI } from '@veloxts/router';
- *
- * const docs = createSwaggerUI({
- *   collections: [userProcedures],
- *   openapi: {
- *     info: { title: 'My API', version: '1.0.0' },
- *   },
- * });
- *
- * app.register(docs);
- * ```
- */
-export function createSwaggerUI(options) {
-    return async (fastify) => {
-        await swaggerUIPlugin(fastify, options);
-    };
-}
-/**
- * Registers multiple procedure collections with Swagger UI
- *
- * Convenience function that sets up both REST routes and documentation.
- *
- * @param fastify - Fastify instance
- * @param options - Documentation options
- *
- * @example
- * ```typescript
- * import { registerDocs } from '@veloxts/router';
- *
- * await registerDocs(app, {
- *   collections: [userProcedures, postProcedures],
- *   openapi: {
- *     info: { title: 'My API', version: '1.0.0' },
- *   },
- * });
- * ```
- */
-export async function registerDocs(fastify, options) {
-    await fastify.register(swaggerUIPlugin, options);
-}
 /**
  * Gets the generated OpenAPI specification without registering routes
  *

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

@@ -6,6 +6,7 @@
  * @module @veloxts/router/openapi/schema-converter
  */
 import { type ZodType } from 'zod';
+import type { ResourceSchema } from '../resource/schema.js';
 import type { JSONSchema } from './types.js';
 /**
  * Options for Zod to JSON Schema conversion
@@ -100,3 +101,15 @@ export declare function createStringSchema(format?: string): JSONSchema;
  * Checks if a schema has any properties
  */
 export declare function schemaHasProperties(schema: JSONSchema | undefined): boolean;
+/**
+ * Converts a ResourceSchema to JSON Schema for OpenAPI, filtered by visibility level
+ *
+ * Iterates the resource's field definitions and includes only fields
+ * visible at the given access level. Nested resource schemas are
+ * converted recursively.
+ *
+ * @param schema - The resource schema
+ * @param level - The access level to generate documentation for (defaults to 'public')
+ * @returns JSON Schema with only the fields visible at the given level
+ */
+export declare function resourceSchemaToJsonSchema(schema: ResourceSchema, level?: string): JSONSchema;

package/dist/openapi/schema-converter.js

@@ -7,6 +7,7 @@
  */
 import { createLogger } from '@veloxts/core';
 import { z } from 'zod';
+import { isFieldVisibleToLevel } from '../resource/visibility.js';
 const log = createLogger('router');
 /**
  * Maps our target names to Zod 4's native `z.toJSONSchema()` target names.
@@ -257,3 +258,53 @@ export function schemaHasProperties(schema) {
         return false;
     return Object.keys(schema.properties).length > 0;
 }
+// ============================================================================
+// Resource Schema to JSON Schema
+// ============================================================================
+/**
+ * Converts a ResourceSchema to JSON Schema for OpenAPI, filtered by visibility level
+ *
+ * Iterates the resource's field definitions and includes only fields
+ * visible at the given access level. Nested resource schemas are
+ * converted recursively.
+ *
+ * @param schema - The resource schema
+ * @param level - The access level to generate documentation for (defaults to 'public')
+ * @returns JSON Schema with only the fields visible at the given level
+ */
+export function resourceSchemaToJsonSchema(schema, level = 'public') {
+    const properties = {};
+    const required = [];
+    for (const field of schema.fields) {
+        if (!isFieldVisibleToLevel(field, level)) {
+            continue;
+        }
+        if (field.nestedSchema) {
+            // Nested relation — recurse
+            const nestedJsonSchema = resourceSchemaToJsonSchema(field.nestedSchema, level);
+            if (field.cardinality === 'many') {
+                properties[field.name] = { type: 'array', items: nestedJsonSchema };
+            }
+            else {
+                properties[field.name] = { ...nestedJsonSchema, nullable: true };
+            }
+        }
+        else if (field.schema) {
+            // Scalar field with Zod schema
+            const fieldJsonSchema = zodSchemaToJsonSchema(field.schema);
+            if (fieldJsonSchema) {
+                properties[field.name] = fieldJsonSchema;
+            }
+        }
+        else {
+            // Field without schema — generic
+            properties[field.name] = {};
+        }
+        required.push(field.name);
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}

package/dist/procedure/builder.js

@@ -85,15 +85,26 @@ function createBuilder(state) {
             });
         },
         /**
-         * Sets the output validation schema
+         * Sets the output validation schema (Zod-only)
          */
         output(schema) {
-            // Return new builder with updated output schema
             return createBuilder({
                 ...state,
                 outputSchema: schema,
             });
         },
+        /**
+         * Sets field-level visibility via a resource schema
+         */
+        expose(schema) {
+            const level = isTaggedResourceSchema(schema) ? schema._level : undefined;
+            return createBuilder({
+                ...state,
+                resourceSchema: schema,
+                resourceLevel: level,
+                outputSchema: undefined,
+            });
+        },
         /**
          * Adds middleware to the chain
          */
@@ -151,6 +162,16 @@ function createBuilder(state) {
                 restOverride: config,
             });
         },
+        /**
+         * Configures the procedure as a webhook endpoint
+         */
+        webhook(path) {
+            return createBuilder({
+                ...state,
+                restOverride: { method: 'POST', path },
+                isWebhook: true,
+            });
+        },
         /**
          * Marks the procedure as deprecated
          */
@@ -200,10 +221,7 @@ function createBuilder(state) {
             return compileProcedure('mutation', handler, state);
         },
         /**
-         * Sets the output type based on a resource schema
-         *
-         * Accepts either a plain `ResourceSchema` or a tagged schema
-         * (e.g., `UserSchema.authenticated`) for declarative auto-projection.
+         * @deprecated Use `.expose()` instead. `.resource()` will be removed in v1.0.
          */
         resource(schema) {
             const level = isTaggedResourceSchema(schema) ? schema._level : undefined;
@@ -211,6 +229,7 @@ function createBuilder(state) {
                 ...state,
                 resourceSchema: schema,
                 resourceLevel: level,
+                outputSchema: undefined,
             });
         },
     };
@@ -240,6 +259,7 @@ function compileProcedure(type, handler, state) {
         restOverride: state.restOverride,
         deprecated: state.deprecated,
         deprecationMessage: state.deprecationMessage,
+        isWebhook: state.isWebhook,
         parentResource: state.parentResource,
         parentResources: state.parentResources,
         // Store pre-compiled executor for performance
@@ -413,14 +433,14 @@ export async function executeProcedure(procedure, rawInput, ctx) {
                 const message = guard.message ?? `Guard "${guard.name}" check failed`;
                 throw new GuardError(guard.name, message, statusCode);
             }
-            // Track highest access level from narrowing guards
+            // Track access level from narrowing guards.
+            // IMPORTANT: last guard's accessLevel wins. With custom levels that
+            // have no inherent hierarchy, ordering of guards matters.
+            // Guards without accessLevel (e.g. plain `authenticated`) do NOT
+            // update the level — it stays at 'public' for .expose() projection.
             const guardWithLevel = guard;
             if (guardWithLevel.accessLevel) {
-                // Admin > authenticated > public
-                if (guardWithLevel.accessLevel === 'admin' ||
-                    (guardWithLevel.accessLevel === 'authenticated' && accessLevel === 'public')) {
-                    accessLevel = guardWithLevel.accessLevel;
-                }
+                accessLevel = guardWithLevel.accessLevel;
             }
         }
     }
@@ -451,15 +471,7 @@ export async function executeProcedure(procedure, rawInput, ctx) {
         // Prefer explicit level from tagged schema over guard-derived level
         const finalLevel = procedure._resourceLevel ?? accessLevel;
         const projectOne = (item) => {
-            const r = new Resource(item, schema);
-            switch (finalLevel) {
-                case 'admin':
-                    return r.forAdmin();
-                case 'authenticated':
-                    return r.forAuthenticated();
-                default:
-                    return r.forAnonymous();
-            }
+            return new Resource(item, schema).forLevel(finalLevel);
         };
         if (Array.isArray(result)) {
             result = result.map((item) => projectOne(item));