@veloxts/router 0.7.4 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/router
 
+## 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
+
+- fix(cli): address sync command review findings
+- Updated dependencies
+  - @veloxts/core@0.7.5
+  - @veloxts/validation@0.7.5
+
 ## 0.7.4
 
 ### 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
@@ -430,7 +430,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 +450,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 +459,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 +469,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 +544,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 +590,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 +611,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';
@@ -83,7 +83,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, 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 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

@@ -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/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));

package/dist/procedure/types.d.ts

@@ -11,7 +11,7 @@
  */
 import type { BaseContext } from '@veloxts/core';
 import type { ZodType } from 'zod';
-import type { OutputForTag, ResourceSchema, TaggedResourceSchema } from '../resource/index.js';
+import type { FilterFieldsByLevel, OutputForTag, ResourceSchema, TaggedResourceSchema } from '../resource/index.js';
 import type { ContextTag, ExtractTag, LevelToTag, TaggedContext } from '../resource/tags.js';
 import type { CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, ProcedureHandler, RestRouteOverride } from '../types.js';
 /**
@@ -94,10 +94,13 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      */
     input<TSchema extends ValidSchema>(schema: TSchema): ProcedureBuilder<InferSchemaOutput<TSchema>, TOutput, TContext>;
     /**
-     * Defines the output validation schema for the procedure
+     * Defines the output validation schema (Zod)
      *
-     * The output type is automatically inferred from the Zod schema.
-     * The handler return type will be validated against this schema.
+     * Sets a Zod schema that validates the handler's return value.
+     * All callers receive the same fields.
+     *
+     * For field-level visibility (different fields per access level),
+     * use `.expose()` with a resource schema instead.
      *
      * @template TSchema - The Zod schema type
      * @param schema - Zod schema for output validation
@@ -106,14 +109,39 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      * @example
      * ```typescript
      * procedure()
-     *   .output(z.object({
-     *     id: z.string(),
-     *     name: z.string(),
-     *   }))
-     *   // handler must return { id: string; name: string }
+     *   .output(z.object({ id: z.string(), name: z.string() }))
+     *   .query(handler) // handler must return { id: string; name: string }
      * ```
      */
     output<TSchema extends ValidSchema>(schema: TSchema): ProcedureBuilder<TInput, InferSchemaOutput<TSchema>, TContext>;
+    /**
+     * Sets field-level visibility via a resource schema
+     *
+     * Accepts two resource schema variants:
+     * 1. **Tagged resource schema** (e.g., `UserSchema.authenticated`) — explicit field projection by access level
+     * 2. **Plain resource schema** (e.g., `UserSchema`) — context-derived field projection from `guardNarrow`
+     *
+     * @template TSchema - The resource schema type
+     * @param schema - Resource schema for field projection
+     * @returns New builder with updated output type
+     *
+     * @example Tagged resource schema — explicit projection level
+     * ```typescript
+     * procedure()
+     *   .guard(authenticated)
+     *   .expose(UserSchema.authenticated) // returns { id, name, email }
+     *   .query(handler)
+     * ```
+     *
+     * @example Plain resource schema — derives level from guardNarrow
+     * ```typescript
+     * procedure()
+     *   .guardNarrow(authenticatedNarrow)
+     *   .expose(UserSchema) // auto-projects based on guard's accessLevel
+     *   .query(handler)
+     * ```
+     */
+    expose<TSchema extends ResourceSchema>(schema: TSchema): ProcedureBuilder<TInput, TSchema extends TaggedResourceSchema<infer TFields, infer TLevel> ? TLevel extends 'admin' | 'authenticated' | 'public' ? OutputForTag<ResourceSchema<TFields>, LevelToTag<TLevel>> : FilterFieldsByLevel<TFields, TLevel> : TContext extends TaggedContext<infer TTag> ? TTag extends ContextTag ? OutputForTag<TSchema, TTag> : OutputForTag<TSchema, ExtractTag<TContext>> : OutputForTag<TSchema, ExtractTag<TContext>>, TContext>;
     /**
      * Adds middleware to the procedure chain
      *
@@ -255,6 +283,26 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      * ```
      */
     rest(config: RestRouteOverride): ProcedureBuilder<TInput, TOutput, TContext>;
+    /**
+     * Configures the procedure as a webhook endpoint
+     *
+     * Sugar for `.rest({ method: 'POST', path })` with a webhook flag.
+     * Webhook procedures expect raw body access for signature verification.
+     *
+     * @param path - The webhook endpoint path (e.g., '/webhooks/stripe')
+     * @returns New builder with webhook configuration
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .webhook('/webhooks/stripe')
+     *   .mutation(async ({ input, ctx }) => {
+     *     const isValid = verifySignature(ctx.request.rawBody, ctx.request.headers['stripe-signature']);
+     *     // ...
+     *   })
+     * ```
+     */
+    webhook(path: string): ProcedureBuilder<TInput, TOutput, TContext>;
     /**
      * Marks the procedure as deprecated
      *
@@ -377,28 +425,17 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      */
     mutation(handler: ProcedureHandler<TInput, TOutput, TContext>): CompiledProcedure<TInput, TOutput, TContext, 'mutation'>;
     /**
-     * Sets the output type based on a resource schema
+     * @deprecated Use `.expose()` instead. `.resource()` will be removed in v1.0.
      *
-     * Accepts either a tagged schema (e.g., `UserSchema.authenticated`) for
-     * explicit auto-projection, or a plain schema for backward compatibility.
+     * Sets field-level visibility via a resource schema.
      *
-     * When a tagged schema is used, the output type is computed from the
-     * tag's access level. When a plain schema is used, the output type is
-     * derived from the context's phantom tag (set by `guardNarrow`).
-     *
-     * @example
+     * @example Migration
      * ```typescript
-     * // Tagged schema — explicit projection level (recommended)
-     * procedure()
-     *   .guard(authenticated)
-     *   .resource(UserSchema.authenticated)
-     *   .query(async ({ ctx }) => ctx.db.user.findUnique(...));
+     * // Before
+     * procedure().resource(UserSchema.authenticated).query(handler)
      *
-     * // Plain schema — derives level from guardNarrow or defaults to public
-     * procedure()
-     *   .guardNarrow(authenticatedNarrow)
-     *   .resource(UserSchema)
-     *   .query(async ({ ctx }) => ctx.db.user.findUnique(...));
+     * // After
+     * procedure().expose(UserSchema.authenticated).query(handler)
      * ```
      */
     resource<TSchema extends ResourceSchema>(schema: TSchema): ProcedureBuilder<TInput, TSchema extends TaggedResourceSchema<infer TFields, infer TLevel> ? OutputForTag<ResourceSchema<TFields>, LevelToTag<TLevel>> : TContext extends TaggedContext<infer TTag> ? TTag extends ContextTag ? OutputForTag<TSchema, TTag> : OutputForTag<TSchema, ExtractTag<TContext>> : OutputForTag<TSchema, ExtractTag<TContext>>, TContext>;
@@ -417,7 +454,7 @@ export interface BuilderRuntimeState {
     /** Resource schema for context-dependent output */
     resourceSchema?: ResourceSchema;
     /** Explicit resource level from tagged schema (e.g., UserSchema.authenticated) */
-    resourceLevel?: 'public' | 'authenticated' | 'admin';
+    resourceLevel?: string;
     /** Middleware chain */
     middlewares: MiddlewareFunction<unknown, BaseContext, BaseContext, unknown>[];
     /** Guards to execute before handler */
@@ -432,6 +469,8 @@ export interface BuilderRuntimeState {
     deprecated?: boolean;
     /** Deprecation message */
     deprecationMessage?: string;
+    /** Whether this procedure is a webhook endpoint (metadata marker) */
+    isWebhook?: boolean;
 }
 /**
  * Type for the procedures object passed to defineProcedures

package/dist/resource/index.d.ts

@@ -34,7 +34,7 @@
  *     .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();
  *     }),
  *
  *   // Authenticated endpoint → returns { id, name, email }
@@ -60,9 +60,11 @@
  * @module resource
  */
 export { Resource, ResourceCollection, resource, resourceCollection } from './instance.js';
-export type { AdminOutput, AnonymousOutput, AuthenticatedOutput, BuilderField, OutputForLevel, OutputForTag, RelationField, ResourceField, ResourceSchema, ResourceSchemaWithViews, RuntimeField, TaggedResourceSchema, } from './schema.js';
+export type { AccessLevelConfig } from './levels.js';
+export { defineAccessLevels } from './levels.js';
+export type { AdminOutput, AnonymousOutput, AuthenticatedOutput, BuilderField, CustomResourceSchemaWithViews, CustomSchemaBuilder, FilterFieldsByLevel, OutputForLevel, OutputForTag, PublicOutput, RelationField, ResourceField, ResourceSchema, ResourceSchemaWithViews, RuntimeField, TaggedResourceSchema, } from './schema.js';
 export { isResourceSchema, isTaggedResourceSchema, ResourceSchemaBuilder, resourceSchema, } from './schema.js';
-export type { AccessLevel, ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, HasTag, LevelToTag, TaggedContext, WithTag, } from './tags.js';
-export type { AdminTaggedContext, AnonymousTaggedContext, AnyResourceOutput, AuthenticatedTaggedContext, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, } from './types.js';
+export type { AccessLevel, ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, HasTag, LevelToTag, PUBLIC, TaggedContext, TagToLevel, WithTag, } from './tags.js';
+export type { AdminTaggedContext, AnonymousTaggedContext, AnyResourceOutput, AuthenticatedTaggedContext, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, PublicTaggedContext, } from './types.js';
 export type { IsVisibleToTag, VisibilityLevel } from './visibility.js';
-export { getAccessibleLevels, getVisibilityForTag, isVisibleAtLevel } from './visibility.js';
+export { getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isVisibleAtLevel, } from './visibility.js';

package/dist/resource/index.js

@@ -34,7 +34,7 @@
  *     .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();
  *     }),
  *
  *   // Authenticated endpoint → returns { id, name, email }
@@ -64,7 +64,8 @@
 // ============================================================================
 // Resource instances
 export { Resource, ResourceCollection, resource, resourceCollection } from './instance.js';
+export { defineAccessLevels } from './levels.js';
 // Schema builder
 export { isResourceSchema, isTaggedResourceSchema, ResourceSchemaBuilder, resourceSchema, } from './schema.js';
 // Visibility
-export { getAccessibleLevels, getVisibilityForTag, isVisibleAtLevel } from './visibility.js';
+export { getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isVisibleAtLevel, } from './visibility.js';