@veloxts/web 0.6.31 → 0.6.51

package/CHANGELOG.md

@@ -1,5 +1,229 @@
 # @veloxts/web
 
+## 0.6.51
+
+### Patch Changes
+
+- fix(web): configure @vinxi/server-functions for RSC server actions
+- Updated dependencies
+  - @veloxts/auth@0.6.51
+  - @veloxts/client@0.6.51
+  - @veloxts/core@0.6.51
+  - @veloxts/router@0.6.51
+
+## 0.6.50
+
+### Patch Changes
+
+- lint fixed
+- Updated dependencies
+  - @veloxts/auth@0.6.50
+  - @veloxts/client@0.6.50
+  - @veloxts/core@0.6.50
+  - @veloxts/router@0.6.50
+
+## 0.6.49
+
+### Patch Changes
+
+- feat(create): add client import lint script for RSC templates
+- Updated dependencies
+  - @veloxts/auth@0.6.49
+  - @veloxts/client@0.6.49
+  - @veloxts/core@0.6.49
+  - @veloxts/router@0.6.49
+
+## 0.6.48
+
+### Patch Changes
+
+- fix(web): remove server-only guards incompatible with Vite SS
+- Updated dependencies
+  - @veloxts/auth@0.6.48
+  - @veloxts/client@0.6.48
+  - @veloxts/core@0.6.48
+  - @veloxts/router@0.6.48
+
+## 0.6.47
+
+### Patch Changes
+
+- fix(web): use /adapters for createH3ApiHandler to avoid server-only
+- Updated dependencies
+  - @veloxts/auth@0.6.47
+  - @veloxts/client@0.6.47
+  - @veloxts/core@0.6.47
+  - @veloxts/router@0.6.47
+
+## 0.6.46
+
+### Patch Changes
+
+- fix(web): remove transitive server-only import from main entry
+- Updated dependencies
+  - @veloxts/auth@0.6.46
+  - @veloxts/client@0.6.46
+  - @veloxts/core@0.6.46
+  - @veloxts/router@0.6.46
+
+## 0.6.45
+
+### Patch Changes
+
+- fix(web): remove server-only guard from main entry for Vinxi compat
+- Updated dependencies
+  - @veloxts/auth@0.6.45
+  - @veloxts/client@0.6.45
+  - @veloxts/core@0.6.45
+  - @veloxts/router@0.6.45
+
+## 0.6.44
+
+### Patch Changes
+
+- refactor(web): implement proper RSC server/client separation
+- fix(web): remove server-only guard from main entry to allow Vinxi config loading
+  - Main entry (`@veloxts/web`) now allows build-time Node.js usage (e.g., `defineVeloxApp` in `app.config.ts`)
+  - RSC runtime protection still enforced via `@veloxts/web/server` and `@veloxts/web/actions` guards
+  - Fixes "This module cannot be imported from a Client Component" error during `vinxi dev`
+- Updated dependencies
+  - @veloxts/auth@0.6.44
+  - @veloxts/client@0.6.44
+  - @veloxts/core@0.6.44
+  - @veloxts/router@0.6.44
+
+## 0.6.43
+
+### Patch Changes
+
+- fix(web): exclude native modules from Vite dependency optimization
+- Updated dependencies
+  - @veloxts/auth@0.6.43
+  - @veloxts/client@0.6.43
+  - @veloxts/core@0.6.43
+  - @veloxts/router@0.6.43
+
+## 0.6.42
+
+### Patch Changes
+
+- fix(web): enable tsconfig path aliases for Vite/Vinxi + docs(web): add @public/@internal JSDoc annotations to server actions
+- Updated dependencies
+  - @veloxts/auth@0.6.42
+  - @veloxts/client@0.6.42
+  - @veloxts/core@0.6.42
+  - @veloxts/router@0.6.42
+
+## 0.6.41
+
+### Patch Changes
+
+- feat(web): add authAction helper for procedure bridge authentication
+- Updated dependencies
+  - @veloxts/auth@0.6.41
+  - @veloxts/client@0.6.41
+  - @veloxts/core@0.6.41
+  - @veloxts/router@0.6.41
+
+## 0.6.40
+
+### Patch Changes
+
+- feat(create): consolidate template styles with unified dark mode design
+- Updated dependencies
+  - @veloxts/auth@0.6.40
+  - @veloxts/client@0.6.40
+  - @veloxts/core@0.6.40
+  - @veloxts/router@0.6.40
+
+## 0.6.39
+
+### Patch Changes
+
+- fix RSC client hydration with split layout architecture
+- Updated dependencies
+  - @veloxts/auth@0.6.39
+  - @veloxts/client@0.6.39
+  - @veloxts/core@0.6.39
+  - @veloxts/router@0.6.39
+
+## 0.6.38
+
+### Patch Changes
+
+- fix client hydration for RSC templates
+- Updated dependencies
+  - @veloxts/auth@0.6.38
+  - @veloxts/client@0.6.38
+  - @veloxts/core@0.6.38
+  - @veloxts/router@0.6.38
+
+## 0.6.37
+
+### Patch Changes
+
+- feat(web): add validated() helper for secure server actions & add rsc-auth template with validated()
+- Updated dependencies
+  - @veloxts/auth@0.6.37
+  - @veloxts/client@0.6.37
+  - @veloxts/core@0.6.37
+  - @veloxts/router@0.6.37
+
+## 0.6.36
+
+### Patch Changes
+
+- Gap Remediation Plan
+- Updated dependencies
+  - @veloxts/auth@0.6.36
+  - @veloxts/client@0.6.36
+  - @veloxts/core@0.6.36
+  - @veloxts/router@0.6.36
+
+## 0.6.35
+
+### Patch Changes
+
+- proper auth template testing in verify-publis
+- Updated dependencies
+  - @veloxts/auth@0.6.35
+  - @veloxts/client@0.6.35
+  - @veloxts/core@0.6.35
+  - @veloxts/router@0.6.35
+
+## 0.6.34
+
+### Patch Changes
+
+- update PostgreSQL adapter for Prisma 7 API
+- Updated dependencies
+  - @veloxts/auth@0.6.34
+  - @veloxts/client@0.6.34
+  - @veloxts/core@0.6.34
+  - @veloxts/router@0.6.34
+
+## 0.6.33
+
+### Patch Changes
+
+- changed claude.md instruction, added prisma config
+- Updated dependencies
+  - @veloxts/auth@0.6.33
+  - @veloxts/client@0.6.33
+  - @veloxts/core@0.6.33
+  - @veloxts/router@0.6.33
+
+## 0.6.32
+
+### Patch Changes
+
+- Introducing new Ecosystem Expansion packages: cache, queue, mail, storage, scheduler, events. Do not use yet
+- Updated dependencies
+  - @veloxts/auth@0.6.32
+  - @veloxts/client@0.6.32
+  - @veloxts/core@0.6.32
+  - @veloxts/router@0.6.32
+
 ## 0.6.31
 
 ### Patch Changes

package/dist/actions/action.d.ts

@@ -35,12 +35,14 @@
  */
 import type { BaseContext } from '@veloxts/core';
 import type { CompiledProcedure } from '@veloxts/router';
-import type { infer as ZodInfer, ZodSchema, ZodType, ZodTypeDef } from 'zod';
+import { type infer as ZodInfer, type ZodSchema, type ZodType, type ZodTypeDef } from 'zod';
+import { type H3ActionContext } from '../adapters/h3-adapter.js';
 import { type ExecuteProcedureOptions } from './procedure-bridge.js';
 import type { ActionContext, ActionError, ActionErrorCode, ActionResult, ActionSuccess, AuthenticatedActionContext } from './types.js';
 /**
  * Handler function that receives validated input and returns output.
  * The context type varies based on whether the action is protected.
+ * @public
  */
 type ActionHandlerFn<TInput, TOutput, TContext extends ActionContext = ActionContext> = (input: TInput, ctx: TContext) => Promise<TOutput>;
 /**
@@ -49,11 +51,13 @@ type ActionHandlerFn<TInput, TOutput, TContext extends ActionContext = ActionCon
  *
  * Note: Named `ValidatedAction` to distinguish from the simpler `ServerAction`
  * type in types.ts which does not wrap the output in ActionResult.
+ * @public
  */
 type ValidatedAction<TInput, TOutput> = (input: TInput) => Promise<ActionResult<TOutput>>;
 /**
  * Configuration options for action creation.
  * These are set via the fluent builder methods.
+ * @public
  */
 interface ActionConfig<TInput, TOutput, TContext extends ActionContext> {
     inputSchema?: ZodSchema<TInput>;
@@ -63,10 +67,12 @@ interface ActionConfig<TInput, TOutput, TContext extends ActionContext> {
 }
 /**
  * Custom error handler type.
+ * @public
  */
 type ErrorHandler<TContext extends ActionContext = ActionContext> = (error: unknown, ctx: TContext) => ActionError | Promise<ActionError>;
 /**
  * Options for creating an action from a procedure.
+ * @public
  */
 interface FromProcedureOptions extends ExecuteProcedureOptions {
     /**
@@ -75,10 +81,53 @@ interface FromProcedureOptions extends ExecuteProcedureOptions {
      * @default false
      */
     parseFormData?: boolean;
+    /**
+     * Called after successful procedure execution.
+     * Use for side effects like setting cookies, logging, etc.
+     *
+     * @param result - The procedure's output
+     * @param ctx - H3 action context with cookie methods
+     *
+     * @example
+     * ```typescript
+     * action.fromProcedure(authProcedures.login, {
+     *   onSuccess: async (tokens, ctx) => {
+     *     ctx.setCookie('accessToken', tokens.accessToken, { httpOnly: true });
+     *   }
+     * });
+     * ```
+     */
+    onSuccess?: (result: unknown, ctx: H3ActionContext) => void | Promise<void>;
+    /**
+     * Called before procedure execution.
+     * Use for extracting data from cookies, setting up context.
+     *
+     * @param ctx - H3 action context with cookie methods
+     */
+    beforeExecute?: (ctx: H3ActionContext) => void | Promise<void>;
+    /**
+     * Transform the result before returning to the client.
+     * Useful for stripping sensitive data (like tokens) from responses.
+     *
+     * @param result - The procedure's raw output
+     * @returns The transformed result
+     *
+     * @example
+     * ```typescript
+     * action.fromProcedure(authProcedures.login, {
+     *   transformResult: (tokens) => ({
+     *     success: true,
+     *     expiresIn: tokens.expiresIn,
+     *   })
+     * });
+     * ```
+     */
+    transformResult?: <T>(result: T) => unknown;
 }
 /**
  * Builder for creating actions with fluent method chaining.
  * Each method returns a new builder with updated type parameters.
+ * @public
  */
 interface ActionBuilder<TInput = unknown, TOutput = unknown, TContext extends ActionContext = ActionContext> {
     /**
@@ -155,6 +204,7 @@ interface ActionBuilder<TInput = unknown, TOutput = unknown, TContext extends Ac
 }
 /**
  * Action helper type - combines function signature with builder methods.
+ * @public
  */
 interface Action {
     /**
@@ -361,6 +411,8 @@ interface Action {
  * ```typescript
  * { success: false, error: { code: 'UNAUTHORIZED', message: 'Authentication required' } }
  * ```
+ *
+ * @public
  */
 declare const action: Action;
 export { action };

package/dist/actions/action.js

@@ -33,6 +33,8 @@
  *   });
  * ```
  */
+import { ZodError, } from 'zod';
+import { createH3Context, isH3Context } from '../adapters/h3-adapter.js';
 import { toActionError } from './error-classifier.js';
 import { formDataToObject } from './form-parser.js';
 import { executeProcedureDirectly } from './procedure-bridge.js';
@@ -41,12 +43,14 @@ import { executeProcedureDirectly } from './procedure-bridge.js';
 // ============================================================================
 /**
  * Creates a successful action result.
+ * @internal
  */
 function ok(data) {
     return { success: true, data };
 }
 /**
  * Creates an error action result.
+ * @internal
  */
 function fail(code, message, details) {
     return {
@@ -59,12 +63,12 @@ function fail(code, message, details) {
 // ============================================================================
 /**
  * Formats a Zod error into an ActionError.
+ * @internal
  */
 function formatZodError(err) {
-    if (err && typeof err === 'object' && 'errors' in err) {
-        const zodError = err;
+    if (err instanceof ZodError) {
         return fail('VALIDATION_ERROR', 'Validation failed', {
-            errors: zodError.errors.map((e) => ({
+            errors: err.errors.map((e) => ({
                 path: e.path.join('.'),
                 message: e.message,
             })),
@@ -81,6 +85,7 @@ function formatZodError(err) {
  * when the schema has async refinements.
  *
  * @see https://zod.dev/?id=parseasync - Zod async parsing docs
+ * @internal
  */
 async function validateWithSchema(schema, data) {
     try {
@@ -114,6 +119,7 @@ async function validateWithSchema(schema, data) {
  *
  * Note: In production with Vinxi integration, this will be replaced
  * with real request context from the server.
+ * @internal
  */
 function createContext() {
     const headers = new Headers();
@@ -126,6 +132,7 @@ function createContext() {
 }
 /**
  * Type guard to check if context has an authenticated user.
+ * @internal
  */
 function hasAuthenticatedUser(ctx) {
     return 'user' in ctx && ctx.user !== undefined && ctx.user !== null;
@@ -140,6 +147,7 @@ function hasAuthenticatedUser(ctx) {
  * for consistent error handling across all action types.
  *
  * @see toActionError - The underlying classification function
+ * @internal
  */
 function handleError(err) {
     return toActionError(err);
@@ -149,6 +157,7 @@ function handleError(err) {
 // ============================================================================
 /**
  * Creates a new builder instance with the given configuration.
+ * @internal
  */
 function createBuilder(config) {
     return {
@@ -183,6 +192,7 @@ function createBuilder(config) {
 }
 /**
  * Creates the final validated action function from config and handler.
+ * @internal
  */
 function createValidatedAction(config, handler) {
     const { inputSchema, outputSchema, requireAuth, onError } = config;
@@ -329,6 +339,8 @@ function createValidatedAction(config, handler) {
  * ```typescript
  * { success: false, error: { code: 'UNAUTHORIZED', message: 'Authentication required' } }
  * ```
+ *
+ * @public
  */
 const action = Object.assign(
 // Primary function signature: action(schema, handler)
@@ -359,18 +371,42 @@ function actionFn(schema, handler) {
         });
     },
     fromProcedure(procedure, options) {
-        const { parseFormData = false, ...executionOptions } = options ?? {};
+        const { parseFormData = false, onSuccess, beforeExecute, transformResult, ...executionOptions } = options ?? {};
         return async (rawInput) => {
             try {
-                // Create context for the action
-                const ctx = createContext();
+                // Try to create real H3 context when running in Vinxi
+                // Falls back to mock context in non-Vinxi environments
+                let ctx;
+                try {
+                    ctx = await createH3Context();
+                }
+                catch {
+                    ctx = createContext();
+                }
+                // Call beforeExecute hook if provided (only for H3 context)
+                if (beforeExecute && isH3Context(ctx)) {
+                    await beforeExecute(ctx);
+                }
                 // Handle FormData if enabled
                 let input = rawInput;
                 if (parseFormData && rawInput instanceof FormData) {
                     input = formDataToObject(rawInput);
                 }
                 // Execute the procedure directly
-                return await executeProcedureDirectly(procedure, input, ctx, executionOptions);
+                const result = await executeProcedureDirectly(procedure, input, ctx, executionOptions);
+                // Call onSuccess hook if execution succeeded (only for H3 context)
+                if (result.success && onSuccess && isH3Context(ctx)) {
+                    await onSuccess(result.data, ctx);
+                }
+                // Transform result if transformer provided
+                // Note: When transformResult is used, the caller is responsible for
+                // providing the correct return type (via type assertion on the function)
+                if (result.success && transformResult) {
+                    const transformedData = transformResult(result.data);
+                    // Return with transformed data - caller handles type via external cast
+                    return { success: true, data: transformedData };
+                }
+                return result;
             }
             catch (err) {
                 return handleError(err);

package/dist/actions/auth-bridge.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Auth Bridge for Server Actions
+ *
+ * Specialized helpers for authentication procedures that need to
+ * set httpOnly cookies for token storage. These helpers wrap
+ * `action.fromProcedure()` with auth-specific callbacks.
+ *
+ * @module @veloxts/web/actions/auth-bridge
+ *
+ * @example
+ * ```typescript
+ * 'use server';
+ *
+ * import { authAction } from '@veloxts/web';
+ * import { authProcedures } from '@/api/procedures/auth';
+ * import { db } from '@/api/database';
+ *
+ * // Login sets tokens in httpOnly cookies
+ * export const login = authAction.fromTokenProcedure(
+ *   authProcedures.procedures.createSession,
+ *   { parseFormData: true, contextExtensions: { db } }
+ * );
+ *
+ * // Logout clears auth cookies
+ * export const logout = authAction.fromLogoutProcedure(
+ *   authProcedures.procedures.deleteSession,
+ *   { contextExtensions: { db } }
+ * );
+ * ```
+ */
+import type { BaseContext } from '@veloxts/core';
+import type { CompiledProcedure } from '@veloxts/router';
+import type { H3ActionContext, H3CookieOptions } from '../adapters/h3-adapter.js';
+import type { ExecuteProcedureOptions } from './procedure-bridge.js';
+import type { ActionResult } from './types.js';
+/**
+ * Configuration for auth cookies.
+ * @public
+ */
+export interface AuthCookieConfig {
+    /**
+     * Name of the access token cookie.
+     * @default 'accessToken'
+     */
+    accessTokenName?: string;
+    /**
+     * Name of the refresh token cookie.
+     * @default 'refreshToken'
+     */
+    refreshTokenName?: string;
+    /**
+     * Cookie options applied to auth cookies.
+     * Merged with secure defaults.
+     */
+    cookieOptions?: H3CookieOptions;
+}
+/**
+ * Options for creating an auth action from a procedure.
+ * @public
+ */
+export interface AuthActionOptions extends ExecuteProcedureOptions {
+    /**
+     * Whether to parse FormData input.
+     * @default false
+     */
+    parseFormData?: boolean;
+    /**
+     * Cookie configuration.
+     */
+    cookies?: AuthCookieConfig;
+}
+/**
+ * Standard token response from auth procedures.
+ * @public
+ */
+export interface TokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    tokenType: string;
+}
+/**
+ * Sanitized login response returned to client.
+ * Raw tokens are stripped for security (stored in httpOnly cookies).
+ * @public
+ */
+export interface LoginResponse {
+    success: boolean;
+    expiresIn: number;
+}
+/**
+ * Extended H3 context with refresh token available.
+ * Used internally by beforeExecute hook in fromRefreshProcedure.
+ * @internal
+ */
+export interface H3ActionContextWithRefreshToken extends H3ActionContext {
+    refreshToken?: string;
+}
+/**
+ * Runtime type guard for TokenResponse.
+ * Validates that the procedure result has the expected token shape.
+ *
+ * @param result - The value to check
+ * @returns True if result is a valid TokenResponse
+ *
+ * @example
+ * ```typescript
+ * if (isTokenResponse(result)) {
+ *   // result is now typed as TokenResponse
+ *   console.log(result.accessToken);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isTokenResponse(result: unknown): result is TokenResponse;
+/**
+ * Auth-specific action helpers for token-based authentication.
+ *
+ * These helpers wrap `action.fromProcedure()` with authentication-specific
+ * callbacks that handle token storage in httpOnly cookies.
+ *
+ * @example
+ * ```typescript
+ * // In your server actions file
+ * 'use server';
+ *
+ * import { authAction } from '@veloxts/web';
+ * import { authProcedures } from '@/api/procedures/auth';
+ *
+ * export const login = authAction.fromTokenProcedure(
+ *   authProcedures.procedures.createSession,
+ *   { parseFormData: true, contextExtensions: { db } }
+ * );
+ *
+ * export const register = authAction.fromTokenProcedure(
+ *   authProcedures.procedures.createAccount,
+ *   { parseFormData: true, contextExtensions: { db } }
+ * );
+ *
+ * export const logout = authAction.fromLogoutProcedure(
+ *   authProcedures.procedures.deleteSession,
+ *   { contextExtensions: { db } }
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare const authAction: {
+    /**
+     * Creates a server action from an auth procedure that returns tokens.
+     *
+     * This helper:
+     * 1. Executes the procedure via the procedure bridge
+     * 2. On success, stores tokens in httpOnly cookies
+     * 3. Returns a sanitized response (tokens stripped for security)
+     *
+     * @param procedure - The auth procedure that returns TokenResponse
+     * @param options - Configuration options
+     * @returns Server action that returns LoginResponse
+     *
+     * @example
+     * ```typescript
+     * export const login = authAction.fromTokenProcedure(
+     *   authProcedures.procedures.createSession,
+     *   {
+     *     parseFormData: true,
+     *     contextExtensions: { db: prisma },
+     *     cookies: {
+     *       accessTokenName: 'session',
+     *       cookieOptions: { sameSite: 'strict' },
+     *     },
+     *   }
+     * );
+     * ```
+     */
+    fromTokenProcedure<TInput, TContext extends BaseContext = BaseContext>(procedure: CompiledProcedure<TInput, TokenResponse, TContext>, options?: AuthActionOptions): (input: TInput) => Promise<ActionResult<LoginResponse>>;
+    /**
+     * Creates a server action from a logout procedure.
+     *
+     * This helper:
+     * 1. Executes the procedure via the procedure bridge
+     * 2. On success, clears auth cookies
+     *
+     * @param procedure - The logout procedure
+     * @param options - Configuration options
+     * @returns Server action that returns the procedure output
+     *
+     * @example
+     * ```typescript
+     * export const logout = authAction.fromLogoutProcedure(
+     *   authProcedures.procedures.deleteSession,
+     *   { contextExtensions: { db: prisma } }
+     * );
+     * ```
+     */
+    fromLogoutProcedure<TInput, TOutput, TContext extends BaseContext = BaseContext>(procedure: CompiledProcedure<TInput, TOutput, TContext>, options?: Omit<AuthActionOptions, "parseFormData">): (input: TInput) => Promise<ActionResult<TOutput>>;
+    /**
+     * Creates a server action from a token refresh procedure.
+     *
+     * This helper:
+     * 1. Reads the refresh token from cookies
+     * 2. Executes the refresh procedure
+     * 3. On success, updates the access token cookie
+     *
+     * @param procedure - The refresh procedure that returns new tokens
+     * @param options - Configuration options
+     * @returns Server action that returns LoginResponse
+     *
+     * @example
+     * ```typescript
+     * export const refreshToken = authAction.fromRefreshProcedure(
+     *   authProcedures.procedures.refreshSession,
+     *   { contextExtensions: { db: prisma } }
+     * );
+     * ```
+     */
+    fromRefreshProcedure<TInput, TContext extends BaseContext = BaseContext>(procedure: CompiledProcedure<TInput, TokenResponse, TContext>, options?: AuthActionOptions): (input: TInput) => Promise<ActionResult<LoginResponse>>;
+};