@veloxts/router 0.6.92 → 0.6.94

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/router
 
+## 0.6.94
+
+### Patch Changes
+
+- feat(client): add tRPC router type support for ClientFromRouter and VeloxHooks
+- Updated dependencies
+  - @veloxts/core@0.6.94
+  - @veloxts/validation@0.6.94
+
+## 0.6.93
+
+### Patch Changes
+
+- feat(router): add Resource API with phantom types for context-dependent outputs
+- Updated dependencies
+  - @veloxts/core@0.6.93
+  - @veloxts/validation@0.6.93
+
 ## 0.6.92
 
 ### Patch Changes

package/GUIDE.md

@@ -28,9 +28,11 @@ export const userProcedures = procedures('users', {
 ## Procedure API
 
 - `.input(schema)` - Validate input with Zod
-- `.output(schema)` - Validate output with Zod
+- `.output(schema)` - Validate output with Zod (same fields for all users)
+- `.resource(schema)` - Context-dependent output with field visibility
 - `.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
@@ -426,6 +428,195 @@ 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.
+
+### Defining a Resource Schema
+
+```typescript
+import { resourceSchema } from '@veloxts/router';
+import { z } from '@veloxts/validation';
+
+const UserSchema = resourceSchema()
+  .public('id', z.string().uuid())           // Visible to everyone
+  .public('name', z.string())                // Visible to everyone
+  .authenticated('email', z.string().email()) // Visible to logged-in users
+  .authenticated('createdAt', z.date())       // Visible to logged-in users
+  .admin('internalNotes', z.string().nullable()) // Visible to admins only
+  .admin('lastLoginIp', z.string().nullable())   // Visible to admins only
+  .build();
+```
+
+### 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:
+
+```typescript
+import { authenticatedNarrow, adminNarrow } from '@veloxts/auth';
+
+export const userProcedures = procedures('users', {
+  // Authenticated endpoint - auto-projects { id, name, email, createdAt }
+  getProfile: procedure()
+    .guardNarrow(authenticatedNarrow)
+    .resource(UserSchema)
+    .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
+  getFullProfile: procedure()
+    .guardNarrow(adminNarrow)
+    .resource(UserSchema)
+    .input(z.object({ id: z.string().uuid() }))
+    .query(async ({ input, ctx }) => {
+      return ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
+    }),
+});
+```
+
+**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
+
+**Benefits:**
+- Clean, declarative code - no projection logic in handlers
+- Type-safe - return types are inferred from guard + schema
+- Less boilerplate - handlers just return data
+- Consistent - impossible to forget projection
+
+### Manual Projection (Complex Cases)
+
+For situations where automatic projection doesn't fit, use explicit projection methods:
+
+```typescript
+import { resource, resourceCollection } from '@veloxts/router';
+
+export const userProcedures = procedures('users', {
+  // Public endpoint - explicitly returns { id, name }
+  getPublicProfile: procedure()
+    .input(z.object({ id: z.string().uuid() }))
+    .query(async ({ input, ctx }) => {
+      const user = await ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
+      return resource(user, UserSchema).forAnonymous();
+    }),
+
+  // Conditional projection based on ownership
+  getOwnProfile: procedure()
+    .guard(authenticated)
+    .input(z.object({ id: z.string().uuid() }))
+    .query(async ({ input, ctx }) => {
+      const user = await ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
+      // Show more fields if viewing own profile
+      if (user.id === ctx.user?.id) {
+        return resource(user, UserSchema).forAuthenticated();
+      }
+      return resource(user, UserSchema).forAnonymous();
+    }),
+
+  // Admin with explicit projection
+  getUserForAdmin: procedure()
+    .guard(hasRole('admin'))
+    .input(z.object({ id: z.string().uuid() }))
+    .query(async ({ input, ctx }) => {
+      const user = await ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
+      return resource(user, UserSchema).forAdmin();
+    }),
+});
+```
+
+**When to use manual projection:**
+- Conditional logic (e.g., show more fields for own profile)
+- Mixed access levels in one handler
+- Non-guard-based access decisions
+- Legacy code migration
+
+### Resource Collections
+
+For arrays of items, use `resourceCollection()`:
+
+```typescript
+// Automatic projection (simple cases)
+const listUsers = procedure()
+  .guardNarrow(authenticatedNarrow)
+  .resource(UserSchema)
+  .query(async ({ ctx }) => {
+    return ctx.db.user.findMany({ take: 50 });
+  });
+
+// Manual projection (when needed)
+const listUsersManual = procedure()
+  .guard(authenticated)
+  .query(async ({ ctx }) => {
+    const users = await ctx.db.user.findMany({ take: 50 });
+    return resourceCollection(users, UserSchema).forAuthenticated();
+  });
+```
+
+### Context-Aware Projection
+
+For manual projection with dynamic access level, use `.for(ctx)`:
+
+```typescript
+const getUser = procedure()
+  .guardNarrow(authenticatedNarrow)
+  .input(z.object({ id: z.string().uuid() }))
+  .query(async ({ input, ctx }) => {
+    const user = await ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
+    // Reads access level from ctx.__accessLevel
+    return resource(user, UserSchema).for(ctx);
+  });
+```
+
+### Visibility Levels
+
+| Method | Fields Included | Use Case |
+|--------|-----------------|----------|
+| `.forAnonymous()` | `public` only | Public APIs, unauthenticated users |
+| `.forAuthenticated()` | `public` + `authenticated` | Logged-in users |
+| `.forAdmin()` | All fields | Admin dashboards, internal tools |
+| `.for(ctx)` | Auto-detected from context | Dynamic access control |
+
+### Type Safety
+
+The Resource API provides compile-time type safety:
+
+```typescript
+// Automatic projection - type inferred from guard
+const getProfile = procedure()
+  .guardNarrow(authenticatedNarrow)
+  .resource(UserSchema)
+  .query(async ({ ctx }) => {
+    return ctx.db.user.findFirst();
+  });
+// Return type: { id: string; name: string; email: string; createdAt: Date }
+
+// Manual projection - type inferred from method
+const result = resource(user, UserSchema).forAnonymous();
+// Type: { id: string; name: string }
+
+const authResult = resource(user, UserSchema).forAuthenticated();
+// Type: { id: string; name: string; email: string; createdAt: Date }
+
+const adminResult = resource(user, UserSchema).forAdmin();
+// Type: { id: string; name: string; email: string; createdAt: Date; internalNotes: string | null; lastLoginIp: string | null }
+```
+
+### Choosing an Approach
+
+| Scenario | Approach |
+|----------|----------|
+| Guard determines access level | **Automatic** (`.guardNarrow().resource()`) |
+| Public endpoints (no guard) | Manual (`.forAnonymous()`) |
+| Conditional/dynamic projection | Manual (`.forX()` in handler) |
+| Simple, declarative code | **Automatic** |
+| Complex access logic | Manual
+
 ## Middleware
 
 ```typescript

package/dist/index.d.ts

@@ -83,3 +83,35 @@ 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, ContextTag, ExtractTag, HasTag, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, IsVisibleToTag, OutputForTag, ResourceField, ResourceSchema, RuntimeField, TaggedContext, VisibilityLevel, WithTag, } from './resource/index.js';
+/**
+ * Resource API for context-dependent output types using phantom types.
+ *
+ * Enables procedures to return different field sets based on user role/auth state
+ * while maintaining precise compile-time types.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { resourceSchema, resource, procedures, procedure } from '@veloxts/router';
+ *
+ * // Define schema with field visibility
+ * const UserSchema = resourceSchema()
+ *   .public('id', z.string())
+ *   .public('name', z.string())
+ *   .authenticated('email', z.string())
+ *   .admin('internalNotes', z.string().nullable())
+ *   .build();
+ *
+ * // Use in procedures
+ * export const userProcedures = procedures('users', {
+ *   getPublicProfile: procedure()
+ *     .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();
+ *     }),
+ * });
+ * ```
+ */
+export { getAccessibleLevels, getVisibilityForTag, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';

package/dist/index.js

@@ -78,3 +78,40 @@ createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CO
 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';
+/**
+ * Resource API for context-dependent output types using phantom types.
+ *
+ * Enables procedures to return different field sets based on user role/auth state
+ * while maintaining precise compile-time types.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { resourceSchema, resource, procedures, procedure } from '@veloxts/router';
+ *
+ * // Define schema with field visibility
+ * const UserSchema = resourceSchema()
+ *   .public('id', z.string())
+ *   .public('name', z.string())
+ *   .authenticated('email', z.string())
+ *   .admin('internalNotes', z.string().nullable())
+ *   .build();
+ *
+ * // Use in procedures
+ * export const userProcedures = procedures('users', {
+ *   getPublicProfile: procedure()
+ *     .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();
+ *     }),
+ * });
+ * ```
+ */
+export { getAccessibleLevels, getVisibilityForTag, isResourceSchema, 
+// Visibility
+isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, 
+// Resource instances
+resource, resourceCollection, 
+// Schema builder
+resourceSchema, } from './resource/index.js';

package/dist/procedure/builder.js

@@ -10,6 +10,7 @@
 import { ConfigurationError, logWarning } from '@veloxts/core';
 import { GuardError } from '../errors.js';
 import { createMiddlewareExecutor, executeMiddlewareChain } from '../middleware/chain.js';
+import { Resource, } from '../resource/index.js';
 import { deriveParentParamName } from '../utils/pluralization.js';
 import { analyzeNamingConvention, isDevelopment, normalizeWarningOption, } from '../warnings.js';
 // ============================================================================
@@ -49,6 +50,7 @@ export function procedure() {
     return createBuilder({
         inputSchema: undefined,
         outputSchema: undefined,
+        resourceSchema: undefined,
         middlewares: [],
         guards: [],
         restOverride: undefined,
@@ -197,6 +199,20 @@ function createBuilder(state) {
         mutation(handler) {
             return compileProcedure('mutation', handler, state);
         },
+        /**
+         * Sets the output type based on a resource schema
+         *
+         * This method stores the resource schema for potential OpenAPI generation
+         * and narrows the output type based on the context's phantom tag.
+         */
+        resource(schema) {
+            // Store the resource schema for OpenAPI generation
+            // The actual output type is computed at the type level
+            return createBuilder({
+                ...state,
+                resourceSchema: schema,
+            });
+        },
     };
 }
 /**
@@ -230,6 +246,8 @@ function compileProcedure(type, handler, state) {
         parentResources: state.parentResources,
         // Store pre-compiled executor for performance
         _precompiledExecutor: precompiledExecutor,
+        // Store resource schema for auto-projection
+        _resourceSchema: state.resourceSchema,
     };
 }
 /**
@@ -388,6 +406,8 @@ export const procedures = defineProcedures;
  * ```
  */
 export async function executeProcedure(procedure, rawInput, ctx) {
+    // Track the highest access level from narrowing guards
+    let accessLevel = 'public';
     // Step 1: Execute guards if any
     if (procedure.guards.length > 0) {
         // Defensive check: ensure request and reply exist in context
@@ -405,8 +425,20 @@ 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
+            const guardWithLevel = guard;
+            if (guardWithLevel.accessLevel) {
+                // Admin > authenticated > public
+                if (guardWithLevel.accessLevel === 'admin' ||
+                    (guardWithLevel.accessLevel === 'authenticated' && accessLevel === 'public')) {
+                    accessLevel = guardWithLevel.accessLevel;
+                }
+            }
         }
     }
+    // Set __accessLevel on context for auto-projection
+    const ctxWithLevel = ctx;
+    ctxWithLevel.__accessLevel = accessLevel;
     // Step 2: Validate input if schema provided
     const input = procedure.inputSchema
         ? procedure.inputSchema.parse(rawInput)
@@ -415,17 +447,33 @@ export async function executeProcedure(procedure, rawInput, ctx) {
     let result;
     if (procedure._precompiledExecutor) {
         // PERFORMANCE: Use pre-compiled middleware chain executor
-        result = await procedure._precompiledExecutor(input, ctx);
+        result = await procedure._precompiledExecutor(input, ctxWithLevel);
     }
     else if (procedure.middlewares.length === 0) {
         // No middleware - execute handler directly
-        result = await procedure.handler({ input, ctx });
+        result = await procedure.handler({ input, ctx: ctxWithLevel });
     }
     else {
         // Fallback: Build middleware chain dynamically (should not normally happen)
-        result = await executeMiddlewareChainFallback(procedure.middlewares, input, ctx, async () => procedure.handler({ input, ctx }));
+        result = await executeMiddlewareChainFallback(procedure.middlewares, input, ctxWithLevel, async () => procedure.handler({ input, ctx: ctxWithLevel }));
+    }
+    // Step 4: Auto-project if resource schema is set
+    if (procedure._resourceSchema) {
+        const schema = procedure._resourceSchema;
+        const resourceInstance = new Resource(result, schema);
+        // Project based on access level
+        switch (accessLevel) {
+            case 'admin':
+                result = resourceInstance.forAdmin();
+                break;
+            case 'authenticated':
+                result = resourceInstance.forAuthenticated();
+                break;
+            default:
+                result = resourceInstance.forAnonymous();
+        }
     }
-    // Step 4: Validate output if schema provided
+    // Step 5: Validate output if schema provided
     if (procedure.outputSchema) {
         return procedure.outputSchema.parse(result);
     }

package/dist/procedure/types.d.ts

@@ -11,6 +11,8 @@
  */
 import type { BaseContext } from '@veloxts/core';
 import type { ZodType, ZodTypeDef } from 'zod';
+import type { OutputForTag, ResourceSchema } from '../resource/index.js';
+import type { ContextTag, ExtractTag, TaggedContext } from '../resource/tags.js';
 import type { CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, ProcedureHandler, RestRouteOverride } from '../types.js';
 /**
  * Internal state type that accumulates type information through the builder chain
@@ -369,6 +371,35 @@ 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 and context tag
+     *
+     * This method enables context-dependent output types using phantom types.
+     * The output type is computed based on the fields visible to the context's
+     * access level (anonymous, authenticated, or admin).
+     *
+     * **IMPORTANT**: This method is for type documentation only. You must still
+     * call `.forAnonymous()`, `.forAuthenticated()`, or `.forAdmin()` on the
+     * resource instance in your handler to perform the actual field filtering.
+     *
+     * @template TSchema - The resource schema type
+     * @param schema - The resource schema defining field visibility
+     * @returns New builder with output type set based on context's tag
+     *
+     * @example
+     * ```typescript
+     * // The output type is automatically computed from the context tag
+     * const getUser = procedure()
+     *   .guardNarrow(authenticatedNarrow) // Tags context with AUTHENTICATED
+     *   .input(z.object({ id: z.string() }))
+     *   .resource(UserSchema) // Output type: { id, name, email }
+     *   .query(async ({ input, ctx }) => {
+     *     const user = await ctx.db.user.findUnique({ where: { id: input.id } });
+     *     return resource(user, UserSchema).forAuthenticated();
+     *   });
+     * ```
+     */
+    resource<TSchema extends ResourceSchema>(schema: TSchema): ProcedureBuilder<TInput, TContext extends TaggedContext<infer TTag> ? TTag extends ContextTag ? OutputForTag<TSchema, TTag> : OutputForTag<TSchema, ExtractTag<TContext>> : OutputForTag<TSchema, ExtractTag<TContext>>, TContext>;
 }
 /**
  * Internal runtime state for the procedure builder
@@ -381,6 +412,8 @@ export interface BuilderRuntimeState {
     inputSchema?: ValidSchema;
     /** Output validation schema */
     outputSchema?: ValidSchema;
+    /** Resource schema for context-dependent output */
+    resourceSchema?: ResourceSchema;
     /** Middleware chain */
     middlewares: MiddlewareFunction<unknown, BaseContext, BaseContext, unknown>[];
     /** Guards to execute before handler */

package/dist/resource/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Resource API with phantom types
+ *
+ * Provides a Laravel-inspired Resource API for defining context-dependent
+ * output types using phantom types for compile-time type safety.
+ *
+ * ## Overview
+ *
+ * The Resource API solves the problem of returning different field sets
+ * based on user role/auth state while maintaining precise types:
+ *
+ * - Anonymous: `{ id, name }`
+ * - Authenticated: `{ id, name, email }`
+ * - Admin: `{ id, name, email, internalNotes }`
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { z } from 'zod';
+ * import { resourceSchema, resource, resourceCollection } from '@veloxts/router';
+ *
+ * // 1. Define schema with field visibility
+ * const UserSchema = resourceSchema()
+ *   .public('id', z.string().uuid())
+ *   .public('name', z.string())
+ *   .authenticated('email', z.string().email())
+ *   .admin('internalNotes', z.string().nullable())
+ *   .build();
+ *
+ * // 2. Use in procedures
+ * export const userProcedures = procedures('users', {
+ *   // Public endpoint → returns { id, name }
+ *   getPublicProfile: procedure()
+ *     .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();
+ *     }),
+ *
+ *   // Authenticated endpoint → returns { id, name, email }
+ *   getProfile: procedure()
+ *     .guardNarrow(authenticatedNarrow)
+ *     .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).forAuthenticated();
+ *     }),
+ *
+ *   // Admin endpoint → returns { id, name, email, internalNotes }
+ *   getFullProfile: procedure()
+ *     .guardNarrow(adminNarrow)
+ *     .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).forAdmin();
+ *     }),
+ * });
+ * ```
+ *
+ * @module resource
+ */
+export { Resource, ResourceCollection, resource, resourceCollection } from './instance.js';
+export type { AdminOutput, AnonymousOutput, AuthenticatedOutput, OutputForTag, ResourceField, ResourceSchema, RuntimeField, } from './schema.js';
+export { isResourceSchema, ResourceSchemaBuilder, resourceSchema } from './schema.js';
+export type { AccessLevel, ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, HasTag, TaggedContext, WithTag, } from './tags.js';
+export type { AdminTaggedContext, AnonymousTaggedContext, AnyResourceOutput, AuthenticatedTaggedContext, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, } from './types.js';
+export type { IsVisibleToTag, VisibilityLevel } from './visibility.js';
+export { getAccessibleLevels, getVisibilityForTag, isVisibleAtLevel } from './visibility.js';

package/dist/resource/index.js

@@ -0,0 +1,70 @@
+/**
+ * Resource API with phantom types
+ *
+ * Provides a Laravel-inspired Resource API for defining context-dependent
+ * output types using phantom types for compile-time type safety.
+ *
+ * ## Overview
+ *
+ * The Resource API solves the problem of returning different field sets
+ * based on user role/auth state while maintaining precise types:
+ *
+ * - Anonymous: `{ id, name }`
+ * - Authenticated: `{ id, name, email }`
+ * - Admin: `{ id, name, email, internalNotes }`
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { z } from 'zod';
+ * import { resourceSchema, resource, resourceCollection } from '@veloxts/router';
+ *
+ * // 1. Define schema with field visibility
+ * const UserSchema = resourceSchema()
+ *   .public('id', z.string().uuid())
+ *   .public('name', z.string())
+ *   .authenticated('email', z.string().email())
+ *   .admin('internalNotes', z.string().nullable())
+ *   .build();
+ *
+ * // 2. Use in procedures
+ * export const userProcedures = procedures('users', {
+ *   // Public endpoint → returns { id, name }
+ *   getPublicProfile: procedure()
+ *     .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();
+ *     }),
+ *
+ *   // Authenticated endpoint → returns { id, name, email }
+ *   getProfile: procedure()
+ *     .guardNarrow(authenticatedNarrow)
+ *     .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).forAuthenticated();
+ *     }),
+ *
+ *   // Admin endpoint → returns { id, name, email, internalNotes }
+ *   getFullProfile: procedure()
+ *     .guardNarrow(adminNarrow)
+ *     .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).forAdmin();
+ *     }),
+ * });
+ * ```
+ *
+ * @module resource
+ */
+// ============================================================================
+// Core Exports
+// ============================================================================
+// Resource instances
+export { Resource, ResourceCollection, resource, resourceCollection } from './instance.js';
+// Schema builder
+export { isResourceSchema, ResourceSchemaBuilder, resourceSchema } from './schema.js';
+// Visibility
+export { getAccessibleLevels, getVisibilityForTag, isVisibleAtLevel } from './visibility.js';