@veloxts/router 0.7.5 → 0.7.7

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';

package/dist/resource/instance.d.ts

@@ -6,8 +6,8 @@
  *
  * @module resource/instance
  */
-import type { OutputForLevel, OutputForTag, ResourceSchema, TaggedResourceSchema } from './schema.js';
-import type { ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, TaggedContext } from './tags.js';
+import type { FilterFieldsByLevel, OutputForLevel, OutputForTag, ResourceSchema, TaggedResourceSchema } from './schema.js';
+import type { ADMIN, AUTHENTICATED, ContextTag, ExtractTag, PUBLIC, TaggedContext } from './tags.js';
 /**
  * A resource instance that can project data based on access level
  *
@@ -23,7 +23,7 @@ import type { ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, TaggedCon
  * const resource = new Resource(user, UserSchema);
  *
  * // Returns only public fields: { id, name }
- * const publicData = resource.forAnonymous();
+ * const publicData = resource.forPublic();
  *
  * // Returns public + authenticated fields: { id, name, email }
  * const authData = resource.forAuthenticated();
@@ -37,11 +37,13 @@ export declare class Resource<TSchema extends ResourceSchema> {
     private readonly _schema;
     constructor(data: Record<string, unknown>, schema: TSchema);
     /**
-     * Projects data for anonymous (unauthenticated) access
+     * Projects data for public (unauthenticated) access
      *
      * Returns only fields marked as 'public'.
      */
-    forAnonymous(): OutputForTag<TSchema, typeof ANONYMOUS>;
+    forPublic(): OutputForTag<TSchema, typeof PUBLIC>;
+    /** @deprecated Use forPublic() */
+    forAnonymous(): OutputForTag<TSchema, typeof PUBLIC>;
     /**
      * Projects data for authenticated user access
      *
@@ -54,6 +56,22 @@ export declare class Resource<TSchema extends ResourceSchema> {
      * Returns all fields (public, authenticated, and admin).
      */
     forAdmin(): OutputForTag<TSchema, typeof ADMIN>;
+    /**
+     * Projects data for an explicit access level string
+     *
+     * Works with both default levels ('public', 'authenticated', 'admin')
+     * and custom levels defined via `defineAccessLevels()`.
+     *
+     * @param level - The access level to project for
+     * @returns Object with only the fields visible to the given level
+     *
+     * @example
+     * ```typescript
+     * // Custom level projection
+     * const data = resource.forLevel('reviewer');
+     * ```
+     */
+    forLevel<TLevel extends string>(level: TLevel): TSchema extends ResourceSchema<infer TFields> ? FilterFieldsByLevel<TFields, TLevel> : Record<string, unknown>;
     /**
      * Projects data based on a tagged context
      *
@@ -70,16 +88,6 @@ export declare class Resource<TSchema extends ResourceSchema> {
      * ```
      */
     for<TContext extends TaggedContext<ContextTag>>(ctx: TContext): OutputForTag<TSchema, ExtractTag<TContext>>;
-    /**
-     * Projects data for an explicit visibility level
-     *
-     * Delegates to the standalone `projectData()` function which supports
-     * recursive projection of nested relations.
-     *
-     * @param level - The visibility level to project for
-     * @returns Object with only the visible fields (null prototype)
-     */
-    private _project;
     /**
      * Infers the visibility level from a context object
      *
@@ -104,7 +112,7 @@ export declare class Resource<TSchema extends ResourceSchema> {
  * const collection = new ResourceCollection(users, UserSchema);
  *
  * // Returns array of public views
- * const publicList = collection.forAnonymous();
+ * const publicList = collection.forPublic();
  *
  * // Returns array with authenticated fields
  * const authList = collection.forAuthenticated();
@@ -115,9 +123,11 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
     private readonly _schema;
     constructor(items: Array<Record<string, unknown>>, schema: TSchema);
     /**
-     * Projects all items for anonymous access
+     * Projects all items for public (unauthenticated) access
      */
-    forAnonymous(): Array<OutputForTag<TSchema, typeof ANONYMOUS>>;
+    forPublic(): Array<OutputForTag<TSchema, typeof PUBLIC>>;
+    /** @deprecated Use forPublic() */
+    forAnonymous(): Array<OutputForTag<TSchema, typeof PUBLIC>>;
     /**
      * Projects all items for authenticated user access
      */
@@ -126,6 +136,14 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
      * Projects all items for admin access
      */
     forAdmin(): Array<OutputForTag<TSchema, typeof ADMIN>>;
+    /**
+     * Projects all items for an explicit access level string
+     *
+     * Works with both default and custom access levels.
+     *
+     * @param level - The access level to project for
+     */
+    forLevel<TLevel extends string>(level: TLevel): TSchema extends ResourceSchema<infer TFields> ? Array<FilterFieldsByLevel<TFields, TLevel>> : Array<Record<string, unknown>>;
     /**
      * Projects all items based on a tagged context
      */
@@ -144,8 +162,8 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
  *
  * When called with a tagged schema (e.g., `UserSchema.authenticated`),
  * returns the projected data directly. When called with an untagged schema,
- * returns a Resource instance with `.forAnonymous()`, `.forAuthenticated()`,
- * `.forAdmin()` methods.
+ * returns a Resource instance with `.forPublic()`, `.forAuthenticated()`,
+ * `.forAdmin()`, `.forLevel()` methods.
  *
  * @param data - The raw data object
  * @param schema - Resource schema (tagged for direct projection, untagged for Resource instance)

package/dist/resource/instance.js

@@ -7,7 +7,7 @@
  * @module resource/instance
  */
 import { isTaggedResourceSchema } from './schema.js';
-import { isVisibleAtLevel } from './visibility.js';
+import { isFieldVisibleToLevel } from './visibility.js';
 // ============================================================================
 // Security Constants
 // ============================================================================
@@ -38,7 +38,7 @@ const MAX_PROJECTION_DEPTH = 10;
  * @internal
  * @param data - The raw data object
  * @param schema - The resource schema to project against
- * @param level - The visibility level to project for
+ * @param level - The access level to project for (any string)
  * @param depth - Current recursion depth (defaults to 0)
  * @param visited - Set of already-visited data objects for cycle detection
  * @returns Projected object with null prototype
@@ -54,7 +54,7 @@ function projectData(data, schema, level, depth = 0, visited) {
     seen.add(data);
     const result = Object.create(null);
     for (const field of schema.fields) {
-        if (!isVisibleAtLevel(field.visibility, level))
+        if (!isFieldVisibleToLevel(field, level))
             continue;
         if (DANGEROUS_PROPERTIES.has(field.name))
             continue;
@@ -107,7 +107,7 @@ function projectData(data, schema, level, depth = 0, visited) {
  * const resource = new Resource(user, UserSchema);
  *
  * // Returns only public fields: { id, name }
- * const publicData = resource.forAnonymous();
+ * const publicData = resource.forPublic();
  *
  * // Returns public + authenticated fields: { id, name, email }
  * const authData = resource.forAuthenticated();
@@ -124,12 +124,16 @@ export class Resource {
         this._schema = schema;
     }
     /**
-     * Projects data for anonymous (unauthenticated) access
+     * Projects data for public (unauthenticated) access
      *
      * Returns only fields marked as 'public'.
      */
+    forPublic() {
+        return this.forLevel('public');
+    }
+    /** @deprecated Use forPublic() */
     forAnonymous() {
-        return this._project('public');
+        return this.forPublic();
     }
     /**
      * Projects data for authenticated user access
@@ -137,7 +141,7 @@ export class Resource {
      * Returns fields marked as 'public' or 'authenticated'.
      */
     forAuthenticated() {
-        return this._project('authenticated');
+        return this.forLevel('authenticated');
     }
     /**
      * Projects data for admin access
@@ -145,7 +149,25 @@ export class Resource {
      * Returns all fields (public, authenticated, and admin).
      */
     forAdmin() {
-        return this._project('admin');
+        return this.forLevel('admin');
+    }
+    /**
+     * Projects data for an explicit access level string
+     *
+     * Works with both default levels ('public', 'authenticated', 'admin')
+     * and custom levels defined via `defineAccessLevels()`.
+     *
+     * @param level - The access level to project for
+     * @returns Object with only the fields visible to the given level
+     *
+     * @example
+     * ```typescript
+     * // Custom level projection
+     * const data = resource.forLevel('reviewer');
+     * ```
+     */
+    forLevel(level) {
+        return projectData(this._data, this._schema, level);
     }
     /**
      * Projects data based on a tagged context
@@ -166,19 +188,7 @@ export class Resource {
         // At runtime, we need to determine the level from context properties
         // Since the tag is phantom (doesn't exist at runtime), we use heuristics
         const level = this._inferLevelFromContext(ctx);
-        return this._project(level);
-    }
-    /**
-     * Projects data for an explicit visibility level
-     *
-     * Delegates to the standalone `projectData()` function which supports
-     * recursive projection of nested relations.
-     *
-     * @param level - The visibility level to project for
-     * @returns Object with only the visible fields (null prototype)
-     */
-    _project(level) {
-        return projectData(this._data, this._schema, level);
+        return this.forLevel(level);
     }
     /**
      * Infers the visibility level from a context object
@@ -232,7 +242,7 @@ export class Resource {
  * const collection = new ResourceCollection(users, UserSchema);
  *
  * // Returns array of public views
- * const publicList = collection.forAnonymous();
+ * const publicList = collection.forPublic();
  *
  * // Returns array with authenticated fields
  * const authList = collection.forAuthenticated();
@@ -246,10 +256,14 @@ export class ResourceCollection {
         this._schema = schema;
     }
     /**
-     * Projects all items for anonymous access
+     * Projects all items for public (unauthenticated) access
      */
+    forPublic() {
+        return this._items.map((item) => new Resource(item, this._schema).forPublic());
+    }
+    /** @deprecated Use forPublic() */
     forAnonymous() {
-        return this._items.map((item) => new Resource(item, this._schema).forAnonymous());
+        return this.forPublic();
     }
     /**
      * Projects all items for authenticated user access
@@ -263,6 +277,16 @@ export class ResourceCollection {
     forAdmin() {
         return this._items.map((item) => new Resource(item, this._schema).forAdmin());
     }
+    /**
+     * Projects all items for an explicit access level string
+     *
+     * Works with both default and custom access levels.
+     *
+     * @param level - The access level to project for
+     */
+    forLevel(level) {
+        return this._items.map((item) => new Resource(item, this._schema).forLevel(level));
+    }
     /**
      * Projects all items based on a tagged context
      */
@@ -284,31 +308,14 @@ export class ResourceCollection {
 }
 export function resource(data, schema) {
     if (isTaggedResourceSchema(schema)) {
-        const r = new Resource(data, schema);
-        switch (schema._level) {
-            case 'admin':
-                return r.forAdmin();
-            case 'authenticated':
-                return r.forAuthenticated();
-            default:
-                return r.forAnonymous();
-        }
+        return new Resource(data, schema).forLevel(schema._level);
     }
     return new Resource(data, schema);
 }
 export function resourceCollection(items, schema) {
     if (isTaggedResourceSchema(schema)) {
-        return items.map((item) => {
-            const r = new Resource(item, schema);
-            switch (schema._level) {
-                case 'admin':
-                    return r.forAdmin();
-                case 'authenticated':
-                    return r.forAuthenticated();
-                default:
-                    return r.forAnonymous();
-            }
-        });
+        const level = schema._level;
+        return items.map((item) => new Resource(item, schema).forLevel(level));
     }
     return new ResourceCollection(items, schema);
 }

package/dist/resource/levels.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Access level configuration for custom visibility systems
+ *
+ * Provides `defineAccessLevels()` for creating custom access level
+ * hierarchies with named groups. The default 3-level system
+ * (public/authenticated/admin) is a special case of this.
+ *
+ * @module resource/levels
+ */
+/**
+ * The built-in 3-level hierarchy used when `resourceSchema()` is called
+ * without arguments.
+ */
+export declare const DEFAULT_LEVELS: readonly ["public", "authenticated", "admin"];
+export type DefaultLevels = typeof DEFAULT_LEVELS;
+/**
+ * Configuration object returned by `defineAccessLevels()`.
+ *
+ * Holds the defined levels, named groups, and a `resolve()` method
+ * that expands a group name to the concrete set of levels it covers.
+ *
+ * @template TLevels - Tuple of level name literals
+ * @template TGroups - Record mapping group names to `'*'` or level arrays
+ */
+export interface AccessLevelConfig<TLevels extends readonly string[] = readonly string[], TGroups extends Record<string, '*' | readonly string[]> = Record<string, never>> {
+    readonly levels: TLevels;
+    readonly groups: TGroups;
+    /** Resolves a group name to the concrete set of levels */
+    resolve(ref: keyof TGroups & string): ReadonlySet<string>;
+    /** Returns the set containing all defined levels */
+    allLevels(): ReadonlySet<string>;
+}
+/**
+ * Defines custom access levels and optional named groups.
+ *
+ * Groups become fluent builder methods on `resourceSchema(config)`.
+ * The `'*'` wildcard resolves to all defined levels.
+ *
+ * @example
+ * ```typescript
+ * const access = defineAccessLevels(
+ *   ['public', 'reviewer', 'authenticated', 'moderator', 'admin'],
+ *   {
+ *     everyone: '*',
+ *     internal: ['reviewer', 'moderator', 'admin'],
+ *     staff: ['moderator', 'admin'],
+ *   }
+ * );
+ * ```
+ */
+export declare function defineAccessLevels<const TLevels extends readonly [string, ...string[]]>(levels: TLevels): AccessLevelConfig<TLevels, Record<string, never>>;
+export declare function defineAccessLevels<const TLevels extends readonly [string, ...string[]], const TGroups extends Record<string, '*' | readonly NoInfer<TLevels[number]>[]>>(levels: TLevels, groups: TGroups): AccessLevelConfig<TLevels, TGroups>;
+/**
+ * Pre-built config for the default 3-level system.
+ *
+ * Used internally by the default `resourceSchema()` builder.
+ * The default levels use a hierarchical model where higher levels
+ * include all fields visible to lower levels.
+ */
+export declare const DEFAULT_ACCESS_LEVELS: AccessLevelConfig<DefaultLevels, Record<string, never>>;
+/**
+ * Converts a default hierarchical level to the set of levels that can see
+ * a field at that visibility.
+ *
+ * - `'public'` → `Set(['public', 'authenticated', 'admin'])`
+ * - `'authenticated'` → `Set(['authenticated', 'admin'])`
+ * - `'admin'` → `Set(['admin'])`
+ *
+ * @internal
+ */
+export declare function defaultLevelToSet(level: string): ReadonlySet<string>;