alepha 0.9.3 → 0.9.5

package/server.d.ts

@@ -1,11 +1,6 @@
-import * as _alepha_core5 from "alepha";
-import * as _alepha_core4 from "alepha";
-import * as _alepha_core11 from "alepha";
-import * as _alepha_core6 from "alepha";
-import * as _alepha_core10 from "alepha";
 import * as _alepha_core1 from "alepha";
-import * as _alepha_core0 from "alepha";
 import { Alepha, AlephaError, Async, Descriptor, FileLike, KIND, Static, StreamLike, TObject, TSchema } from "alepha";
+import * as _alepha_logger0 from "alepha/logger";
 import { Readable } from "node:stream";
 import { ReadableStream } from "node:stream/web";
 import { Route, RouterProvider } from "alepha/router";
@@ -13,27 +8,55 @@ import * as _alepha_cache0 from "alepha/cache";
 import { IncomingMessage, ServerResponse as ServerResponse$1 } from "node:http";
 import { DateTimeProvider, DurationLike } from "alepha/datetime";
 import * as _sinclair_typebox0 from "@sinclair/typebox";
-import * as _sinclair_typebox25 from "@sinclair/typebox";
-import * as _sinclair_typebox35 from "@sinclair/typebox";
 import * as http0 from "http";
 
 //#region src/constants/routeMethods.d.ts
 declare const routeMethods: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "CONNECT", "TRACE"];
 type RouteMethod = (typeof routeMethods)[number];
-//# sourceMappingURL=routeMethods.d.ts.map
 //#endregion
 //#region src/helpers/ServerReply.d.ts
+/**
+ * Helper for building server replies.
+ */
 declare class ServerReply {
   headers: Record<string, string> & {
     "set-cookie"?: string[];
   };
   status?: number;
   body?: any;
+  /**
+   * Redirect to a given URL with optional status code (default 302).
+   */
   redirect(url: string, status?: number): void;
-  setStatus(status: number): void;
-  setHeader(name: string, value: string): void;
+  /**
+   * Set the response status code.
+   */
+  setStatus(status: number): this;
+  /**
+   * Set a response header.
+   */
+  setHeader(name: string, value: string): this;
+  /**
+   * Set the response body.
+   */
+  setBody(body: any): this;
+}
+//#endregion
+//#region src/services/UserAgentParser.d.ts
+interface UserAgentInfo {
+  os: "Windows" | "Android" | "Ubuntu" | "MacOS" | "iOS" | "Linux" | "FreeBSD" | "OpenBSD" | "ChromeOS" | "BlackBerry" | "Symbian" | "Windows Phone";
+  browser: "Chrome" | "Firefox" | "Safari" | "Edge" | "Opera" | "Internet Explorer" | "Brave" | "Vivaldi" | "Samsung Browser" | "UC Browser" | "Yandex";
+  device: "Mobile" | "Desktop" | "Tablet";
+}
+/**
+ * Simple User-Agent parser to detect OS, browser, and device type.
+ * This parser is not exhaustive and may not cover all edge cases.
+ *
+ * Use result for non
+ */
+declare class UserAgentParser {
+  parse(userAgent?: string): UserAgentInfo;
 }
-//# sourceMappingURL=ServerReply.d.ts.map
 //#endregion
 //#region src/interfaces/ServerRequest.d.ts
 interface RequestConfigSchema {
@@ -53,11 +76,44 @@ type ServerRequestConfigEntry<TConfig extends RequestConfigSchema = RequestConfi
 interface ServerRequest<TConfig extends RequestConfigSchema = RequestConfigSchema> extends ServerRequestConfig<TConfig> {
   method: RouteMethod;
   url: URL;
+  requestId: string;
+  /**
+   * Client IP address.
+   * Will parse `X-Forwarded-For` header if present.
+   */
+  ip?: string;
+  /**
+   * Value of the `Host` header sent by the client.
+   */
+  host?: string;
+  /**
+   * Browser user agent information.
+   * Information are not guaranteed to be accurate. Use with caution.
+   *
+   * @see {@link UserAgentParser}
+   */
+  userAgent: UserAgentInfo;
   metadata: Record<string, any>;
+  /**
+   * Reply object to be used to send response.
+   */
   reply: ServerReply;
+  /**
+   * Raw request and response objects from platform.
+   * You should avoid using this property as much as possible to keep your code platform-agnostic.
+   */
   raw: {
+    /**
+     * Node.js request and response objects.
+     */
     node?: {
+      /**
+       * Node.js IncomingMessage object. (request)
+       */
       req: IncomingMessage;
+      /**
+       * Node.js ServerResponse object. (response)
+       */
       res: ServerResponse$1;
     };
   };
@@ -81,8 +137,9 @@ interface ServerResponse {
   headers: Record<string, string>;
   status: number;
 }
+type ServerRouteRequestHandler = (request: ServerRawRequest) => Promise<ServerResponse>;
 interface ServerRouteMatcher extends Route {
-  handler: (request: ServerRawRequest) => Promise<ServerResponse>;
+  handler: ServerRouteRequestHandler;
 }
 interface ServerRawRequest {
   method: RouteMethod;
@@ -97,7 +154,6 @@ interface ServerRawRequest {
     };
   };
 }
-//# sourceMappingURL=ServerRequest.d.ts.map
 //#endregion
 //#region src/providers/ServerProvider.d.ts
 declare abstract class ServerProvider {
@@ -105,8 +161,32 @@ declare abstract class ServerProvider {
   abstract get hostname(): string;
   protected isViteNotFound(url?: string, route?: Route, params?: Record<string, string>): boolean;
 }
-//# sourceMappingURL=ServerProvider.d.ts.map
-
+//#endregion
+//#region src/services/ServerRequestParser.d.ts
+declare class ServerRequestParser {
+  protected readonly alepha: Alepha;
+  protected readonly userAgentParser: UserAgentParser;
+  createServerRequest(rawRequest: ServerRawRequest): ServerRequest;
+  getRequestId(request: ServerRawRequest): string | undefined;
+  getRequestUserAgent(request: ServerRawRequest): UserAgentInfo;
+  getRequestIp(request: ServerRawRequest): string | undefined;
+}
+//#endregion
+//#region src/providers/ServerTimingProvider.d.ts
+type TimingMap = Record<string, [number, number]>;
+declare class ServerTimingProvider {
+  protected readonly log: _alepha_logger0.Logger;
+  protected readonly alepha: Alepha;
+  options: {
+    disabled: boolean;
+  };
+  readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
+  readonly onResponse: _alepha_core1.HookDescriptor<"server:onResponse">;
+  protected get handlerName(): string;
+  beginTiming(name: string): void;
+  endTiming(name: string): void;
+  protected setDuration(name: string, timing: TimingMap): void;
+}
 //#endregion
 //#region src/providers/ServerRouterProvider.d.ts
 /**
@@ -119,9 +199,10 @@ declare abstract class ServerProvider {
 declare class ServerRouterProvider extends RouterProvider<ServerRouteMatcher> {
   protected readonly alepha: Alepha;
   protected readonly routes: ServerRoute[];
+  protected readonly serverTimingProvider: ServerTimingProvider;
+  protected readonly serverRequestParser: ServerRequestParser;
   getRoutes(): ServerRoute[];
   createRoute<TConfig extends RequestConfigSchema = RequestConfigSchema>(route: ServerRoute<TConfig>): void;
-  onRequest(route: ServerRoute, rawRequest: ServerRawRequest, responseKind: ResponseKind): Promise<ServerResponse>;
   protected processRequest(request: ServerRequest, route: ServerRoute, responseKind: ResponseKind): Promise<{
     status: number;
     headers: Record<string, string> & {
@@ -130,18 +211,17 @@ declare class ServerRouterProvider extends RouterProvider<ServerRouteMatcher> {
     body: any;
   }>;
   protected runRouteHandler(route: ServerRoute, request: ServerRequest, responseKind: ResponseKind): Promise<void>;
+  serializeResponse(route: ServerRoute, reply: ServerReply, responseKind: ResponseKind): void;
   protected getResponseType(schema?: RequestConfigSchema): ResponseKind;
   protected errorHandler(route: ServerRoute, request: ServerRequest, error: Error): Promise<void>;
   validateRequest(route: {
     schema?: RequestConfigSchema;
   }, request: ServerRequestConfig): void;
-  serializeResponse(route: ServerRoute, reply: ServerReply, responseKind: ResponseKind): void;
 }
-//# sourceMappingURL=ServerRouterProvider.d.ts.map
 //#endregion
 //#region src/services/HttpClient.d.ts
 declare class HttpClient {
-  protected readonly log: _alepha_core5.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly alepha: Alepha;
   readonly cache: _alepha_cache0.CacheDescriptorFn<HttpClientCache, any[]>;
   protected readonly pendingRequests: HttpClientPendingRequests;
@@ -203,6 +283,7 @@ interface HttpAction {
   method?: string;
   prefix?: string;
   path: string;
+  requestBodyType?: string;
   schema?: {
     params?: TObject;
     query?: TObject;
@@ -213,21 +294,540 @@ interface HttpAction {
 //#endregion
 //#region src/descriptors/$action.d.ts
 /**
- * Create an action endpoint.
+ * Creates a server action descriptor for defining type-safe HTTP endpoints.
+ *
+ * Server actions are the core building blocks for REST APIs in the Alepha framework. They provide
+ * a declarative way to define HTTP endpoints with full TypeScript type safety, automatic schema
+ * validation, and integrated security features. Actions automatically handle routing, request
+ * parsing, response serialization, and OpenAPI documentation generation.
+ *
+ * **Key Features**
+ *
+ * - **Type Safety**: Full TypeScript inference for request/response types
+ * - **Schema Validation**: Automatic validation using TypeBox schemas
+ * - **Auto-routing**: Convention-based URL generation with customizable paths
+ * - **Multiple Invocation**: Call directly (`run()`) or via HTTP (`fetch()`)
+ * - **OpenAPI Integration**: Automatic documentation generation
+ * - **Security Integration**: Built-in authentication and authorization support
+ * - **Content Type Detection**: Automatic handling of JSON, form-data, and plain text
+ *
+ * **URL Generation**
+ *
+ * By default, actions are prefixed with `/api` (configurable via `SERVER_API_PREFIX`):
+ * - Property name becomes the endpoint path
+ * - Path parameters are automatically detected from schema
+ * - HTTP method defaults to GET, or POST if body schema is provided
+ *
+ * **Use Cases**
+ *
+ * Perfect for building robust REST APIs:
+ * - CRUD operations with full type safety
+ * - File upload and download endpoints
+ * - Real-time data processing APIs
+ * - Integration with external services
+ * - Microservice communication
+ * - Admin and management interfaces
+ *
+ * @example
+ * **Basic CRUD operations:**
+ * ```ts
+ * import { $action } from "alepha/server";
+ * import { t } from "alepha";
+ *
+ * class UserController {
+ *   // GET /api/users
+ *   getUsers = $action({
+ *     description: "Retrieve all users with pagination",
+ *     schema: {
+ *       query: t.object({
+ *         page: t.optional(t.number({ default: 1 })),
+ *         limit: t.optional(t.number({ default: 10, maximum: 100 })),
+ *         search: t.optional(t.string())
+ *       }),
+ *       response: t.object({
+ *         users: t.array(t.object({
+ *           id: t.string(),
+ *           name: t.string(),
+ *           email: t.string(),
+ *           createdAt: t.datetime()
+ *         })),
+ *         total: t.number(),
+ *         hasMore: t.boolean()
+ *       })
+ *     },
+ *     handler: async ({ query }) => {
+ *       const { page, limit, search } = query;
+ *       const users = await this.userService.findUsers({ page, limit, search });
+ *
+ *       return {
+ *         users: users.items,
+ *         total: users.total,
+ *         hasMore: (page * limit) < users.total
+ *       };
+ *     }
+ *   });
+ *
+ *   // POST /api/users
+ *   createUser = $action({
+ *     description: "Create a new user account",
+ *     schema: {
+ *       body: t.object({
+ *         name: t.string({ minLength: 2, maxLength: 100 }),
+ *         email: t.string({ format: "email" }),
+ *         password: t.string({ minLength: 8 }),
+ *         role: t.optional(t.enum(["user", "admin"]))
+ *       }),
+ *       response: t.object({
+ *         id: t.string(),
+ *         name: t.string(),
+ *         email: t.string(),
+ *         role: t.string(),
+ *         createdAt: t.datetime()
+ *       })
+ *     },
+ *     handler: async ({ body }) => {
+ *       // Password validation and hashing
+ *       await this.authService.validatePassword(body.password);
+ *       const hashedPassword = await this.authService.hashPassword(body.password);
+ *
+ *       // Create user with default role
+ *       const user = await this.userService.create({
+ *         ...body,
+ *         password: hashedPassword,
+ *         role: body.role || "user"
+ *       });
+ *
+ *       // Return user without password
+ *       const { password, ...publicUser } = user;
+ *       return publicUser;
+ *     }
+ *   });
+ *
+ *   // GET /api/users/:id
+ *   getUser = $action({
+ *     description: "Retrieve user by ID",
+ *     schema: {
+ *       params: t.object({
+ *         id: t.string()
+ *       }),
+ *       response: t.object({
+ *         id: t.string(),
+ *         name: t.string(),
+ *         email: t.string(),
+ *         role: t.string(),
+ *         profile: t.optional(t.object({
+ *           bio: t.string(),
+ *           avatar: t.string({ format: "uri" }),
+ *           location: t.string()
+ *         }))
+ *       })
+ *     },
+ *     handler: async ({ params }) => {
+ *       const user = await this.userService.findById(params.id);
+ *       if (!user) {
+ *         throw new Error(`User not found: ${params.id}`);
+ *       }
+ *       return user;
+ *     }
+ *   });
  *
- * By default, all actions are prefixed by `/api`.
- * If `name` is not provided, the action will be named after the property key.
- * If `path` is not provided, the action will be named after the function name.
+ *   // PUT /api/users/:id
+ *   updateUser = $action({
+ *     method: "PUT",
+ *     description: "Update user information",
+ *     schema: {
+ *       params: t.object({ id: t.string() }),
+ *       body: t.object({
+ *         name: t.optional(t.string({ minLength: 2 })),
+ *         email: t.optional(t.string({ format: "email" })),
+ *         profile: t.optional(t.object({
+ *           bio: t.optional(t.string()),
+ *           avatar: t.optional(t.string({ format: "uri" })),
+ *           location: t.optional(t.string())
+ *         }))
+ *       }),
+ *       response: t.object({
+ *         id: t.string(),
+ *         name: t.string(),
+ *         email: t.string(),
+ *         updatedAt: t.datetime()
+ *       })
+ *     },
+ *     handler: async ({ params, body }) => {
+ *       const updatedUser = await this.userService.update(params.id, body);
+ *       return updatedUser;
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **File upload with multipart form data:**
+ * ```ts
+ * class FileController {
+ *   uploadAvatar = $action({
+ *     method: "POST",
+ *     description: "Upload user avatar image",
+ *     schema: {
+ *       body: t.object({
+ *         file: t.file({
+ *           maxSize: 5 * 1024 * 1024, // 5MB
+ *           allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"]
+ *         }),
+ *         userId: t.string()
+ *       }),
+ *       response: t.object({
+ *         url: t.string({ format: "uri" }),
+ *         size: t.number(),
+ *         mimeType: t.string(),
+ *         uploadedAt: t.datetime()
+ *       })
+ *     },
+ *     handler: async ({ body }) => {
+ *       const { file, userId } = body;
+ *
+ *       // Validate file
+ *       await this.fileService.validateImage(file);
+ *
+ *       // Generate unique filename
+ *       const filename = `avatars/${userId}/${Date.now()}-${file.name}`;
+ *
+ *       // Upload to storage
+ *       const uploadResult = await this.storageService.upload(filename, file);
+ *
+ *       // Update user profile
+ *       await this.userService.updateAvatar(userId, uploadResult.url);
+ *
+ *       return {
+ *         url: uploadResult.url,
+ *         size: file.size,
+ *         mimeType: file.type,
+ *         uploadedAt: new Date().toISOString()
+ *       };
+ *     }
+ *   });
+ *
+ *   downloadFile = $action({
+ *     method: "GET",
+ *     description: "Download file by ID",
+ *     schema: {
+ *       params: t.object({ id: t.string() }),
+ *       query: t.object({
+ *         download: t.optional(t.boolean()),
+ *         thumbnail: t.optional(t.boolean())
+ *       }),
+ *       response: t.file()
+ *     },
+ *     handler: async ({ params, query, reply, user }) => {
+ *       const file = await this.fileService.findById(params.id);
+ *       if (!file) {
+ *         throw new Error("File not found");
+ *       }
+ *
+ *       // Check permissions
+ *       await this.fileService.checkAccess(params.id, user.id);
+ *
+ *       const fileBuffer = query.thumbnail
+ *         ? await this.fileService.getThumbnail(file.id)
+ *         : await this.fileService.getBuffer(file.path);
+ *
+ *       // Set appropriate headers
+ *       reply.header("Content-Type", file.mimeType);
+ *       reply.header("Content-Length", fileBuffer.length);
+ *
+ *       if (query.download) {
+ *         reply.header("Content-Disposition", `attachment; filename="${file.name}"`);
+ *       }
+ *
+ *       return fileBuffer;
+ *     }
+ *   });
+ * }
+ * ```
  *
  * @example
+ * **Advanced API with custom paths and grouped operations:**
  * ```ts
- * class MyController {
- *   hello = $action({
- *     handler: () => "Hello World",
- *   })
+ * class OrderController {
+ *   group = "orders"; // Groups all actions under "orders" tag
+ *
+ *   // GET /api/orders/search
+ *   searchOrders = $action({
+ *     name: "search",
+ *     path: "/orders/search", // Custom path
+ *     description: "Advanced order search with filtering",
+ *     schema: {
+ *       query: t.object({
+ *         status: t.optional(t.union([
+ *           t.literal("pending"),
+ *           t.literal("processing"),
+ *           t.literal("shipped"),
+ *           t.literal("delivered"),
+ *           t.literal("cancelled")
+ *         ])),
+ *         customerId: t.optional(t.string()),
+ *         dateFrom: t.optional(t.date()),
+ *         dateTo: t.optional(t.date()),
+ *         minAmount: t.optional(t.number({ minimum: 0 })),
+ *         maxAmount: t.optional(t.number({ minimum: 0 })),
+ *         sortBy: t.optional(t.union([
+ *           t.literal("createdAt"),
+ *           t.literal("amount"),
+ *           t.literal("status")
+ *         ])),
+ *         sortOrder: t.optional(t.enum(["asc", "desc"]))
+ *       }),
+ *       response: t.object({
+ *         orders: t.array(t.object({
+ *           id: t.string(),
+ *           orderNumber: t.string(),
+ *           customerId: t.string(),
+ *           customerName: t.string(),
+ *           status: t.string(),
+ *           totalAmount: t.number(),
+ *           createdAt: t.datetime(),
+ *           itemCount: t.number()
+ *         })),
+ *         pagination: t.object({
+ *           page: t.number(),
+ *           limit: t.number(),
+ *           total: t.number(),
+ *           hasMore: t.boolean()
+ *         }),
+ *         filters: t.object({
+ *           appliedFilters: t.array(t.string()),
+ *           availableStatuses: t.array(t.string())
+ *         })
+ *       })
+ *     },
+ *     handler: async ({ query }) => {
+ *       // Build dynamic query based on filters
+ *       const searchCriteria = this.orderService.buildSearchCriteria(query);
+ *       const results = await this.orderService.searchOrders(searchCriteria);
+ *
+ *       return {
+ *         orders: results.orders,
+ *         pagination: results.pagination,
+ *         filters: {
+ *           appliedFilters: Object.keys(query).filter(key => query[key] !== undefined),
+ *           availableStatuses: await this.orderService.getAvailableStatuses()
+ *         }
+ *       };
+ *     }
+ *   });
+ *
+ *   // POST /api/orders/:id/process
+ *   processOrder = $action({
+ *     method: "POST",
+ *     path: "/orders/:id/process",
+ *     description: "Process an order through the fulfillment workflow",
+ *     schema: {
+ *       params: t.object({ id: t.string() }),
+ *       body: t.object({
+ *         notes: t.optional(t.string()),
+ *         priority: t.optional(t.union([
+ *           t.literal("low"),
+ *           t.literal("normal"),
+ *           t.literal("high"),
+ *           t.literal("urgent")
+ *         ])),
+ *         assignToWarehouse: t.optional(t.string())
+ *       }),
+ *       response: t.object({
+ *         orderId: t.string(),
+ *         status: t.string(),
+ *         processedAt: t.datetime(),
+ *         estimatedFulfillment: t.datetime(),
+ *         trackingInfo: t.optional(t.object({
+ *           trackingNumber: t.string(),
+ *           carrier: t.string(),
+ *           estimatedDelivery: t.date()
+ *         }))
+ *       })
+ *     },
+ *     handler: async ({ params, body, user }) => {
+ *       // Validate order can be processed
+ *       const order = await this.orderService.findById(params.id);
+ *       if (!order || order.status !== "pending") {
+ *         throw new Error("Order cannot be processed in current status");
+ *       }
+ *
+ *       // Check inventory availability
+ *       const inventoryCheck = await this.inventoryService.checkAvailability(order.items);
+ *       if (!inventoryCheck.available) {
+ *         throw new Error(`Insufficient inventory: ${inventoryCheck.missingItems.join(", ")}`);
+ *       }
+ *
+ *       // Process the order
+ *       const processResult = await this.fulfillmentService.processOrder({
+ *         orderId: params.id,
+ *         options: {
+ *           notes: body.notes,
+ *           priority: body.priority || "normal",
+ *           warehouse: body.assignToWarehouse
+ *         }
+ *       });
+ *
+ *       // Update order status
+ *       await this.orderService.updateStatus(params.id, "processing", {
+ *         processedBy: user.id,
+ *         processedAt: new Date(),
+ *         notes: body.notes
+ *       });
+ *
+ *       // Send notification
+ *       await this.notificationService.sendOrderUpdate(order.customerId, {
+ *         orderId: params.id,
+ *         status: "processing",
+ *         message: "Your order is now being processed"
+ *       });
+ *
+ *       return {
+ *         orderId: params.id,
+ *         status: "processing",
+ *         processedAt: new Date().toISOString(),
+ *         estimatedFulfillment: processResult.estimatedCompletion,
+ *         trackingInfo: processResult.trackingInfo
+ *       };
+ *     }
+ *   });
  * }
- * // GET /api/hello -> "Hello World"
  * ```
+ *
+ * @example
+ * **Actions with security integration and role-based access:**
+ * ```ts
+ * class AdminController {
+ *   group = "admin";
+ *
+ *   // Only accessible to users with "admin:users:read" permission
+ *   getUserStats = $action({
+ *     description: "Get comprehensive user statistics",
+ *     security: { permissions: ["admin:users:read"] },
+ *     schema: {
+ *       query: t.object({
+ *         includeInactive: t.optional(t.boolean())
+ *       }),
+ *       response: t.object({
+ *         totalUsers: t.number(),
+ *         activeUsers: t.number(),
+ *         newUsers: t.number(),
+ *         userGrowth: t.number(),
+ *         breakdown: t.object({
+ *           byRole: t.record(t.string(), t.number()),
+ *           byStatus: t.record(t.string(), t.number()),
+ *           byRegistrationSource: t.record(t.string(), t.number())
+ *         }),
+ *         trends: t.array(t.object({
+ *           date: t.date(),
+ *           registrations: t.number(),
+ *           activations: t.number()
+ *         }))
+ *       })
+ *     },
+ *     handler: async ({ query, user }) => {
+ *       // user is available through security integration
+ *       this.auditLogger.log({
+ *         action: "admin.getUserStats",
+ *         userId: user.id,
+ *         userRole: user.role,
+ *         timestamp: new Date()
+ *       });
+ *
+ *       const period = query.period || "month";
+ *       const stats = await this.analyticsService.getUserStatistics({
+ *         period,
+ *         includeInactive: query.includeInactive || false
+ *       });
+ *
+ *       return stats;
+ *     }
+ *   });
+ *
+ *   // Bulk operations with transaction support
+ *   bulkUpdateUsers = $action({
+ *     method: "POST",
+ *     path: "/admin/users/bulk-update",
+ *     description: "Bulk update user properties",
+ *     security: { permissions: ["admin:users:write"] },
+ *     schema: {
+ *       body: t.object({
+ *         userIds: t.array(t.string(), { minItems: 1, maxItems: 1000 }),
+ *         updates: t.object({
+ *           status: t.optional(t.union([t.literal("active"), t.literal("inactive")])),
+ *           role: t.optional(t.string()),
+ *           tags: t.optional(t.array(t.string())),
+ *           customFields: t.optional(t.record(t.string(), t.any()))
+ *         }),
+ *         reason: t.string({ minLength: 10, maxLength: 500 })
+ *       }),
+ *       response: t.object({
+ *         updated: t.number(),
+ *         failed: t.number(),
+ *         errors: t.array(t.object({
+ *           userId: t.string(),
+ *           error: t.string()
+ *         })),
+ *         auditLogId: t.string()
+ *       })
+ *     },
+ *     handler: async ({ body, user }) => {
+ *       const results = { updated: 0, failed: 0, errors: [] };
+ *
+ *       // Create audit log entry
+ *       const auditLogId = await this.auditService.logBulkOperation({
+ *         operation: "bulk_user_update",
+ *         initiatedBy: user.id,
+ *         targetCount: body.userIds.length,
+ *         reason: body.reason,
+ *         changes: body.updates
+ *       });
+ *
+ *       // Process in batches to avoid overwhelming the database
+ *       const batchSize = 50;
+ *       for (let i = 0; i < body.userIds.length; i += batchSize) {
+ *         const batch = body.userIds.slice(i, i + batchSize);
+ *
+ *         try {
+ *           const updateResult = await this.userService.bulkUpdate(batch, body.updates);
+ *           results.updated += updateResult.success;
+ *           results.failed += updateResult.failed;
+ *           results.errors.push(...updateResult.errors);
+ *         } catch (error) {
+ *           // Log batch failure but continue processing
+ *           this.logger.error(`Bulk update batch failed`, {
+ *             batch: i / batchSize + 1,
+ *             userIds: batch,
+ *             error: error.message
+ *           });
+ *
+ *           results.failed += batch.length;
+ *           results.errors.push(...batch.map(userId => ({
+ *             userId,
+ *             error: error.message
+ *           })));
+ *         }
+ *       }
+ *
+ *       // Update audit log with results
+ *       await this.auditService.updateBulkOperationResults(auditLogId, results);
+ *
+ *       return { ...results, auditLogId };
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * **Important Notes**:
+ * - Actions are automatically registered with the HTTP server when the service is initialized
+ * - Use `run()` for direct invocation (testing, internal calls, or remote services)
+ * - Use `fetch()` for explicit HTTP requests (client-side, external services)
+ * - Schema validation occurs automatically for all requests and responses
+ * - Path parameters are automatically extracted from schema definitions
+ * - Content-Type headers are automatically set based on schema types
+ * - Actions can be disabled via the `disabled` option for maintenance or feature flags
+ *
+ * @stability 2
  */
 declare const $action: {
   <TConfig extends RequestConfigSchema>(options: ActionDescriptorOptions<TConfig>): ActionDescriptor<TConfig>;
@@ -300,7 +900,7 @@ interface ActionDescriptorOptions<TConfig extends RequestConfigSchema> extends O
   handler: ServerActionHandler<TConfig>;
 }
 declare class ActionDescriptor<TConfig extends RequestConfigSchema> extends Descriptor<ActionDescriptorOptions<TConfig>> {
-  protected readonly log: _alepha_core4.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly env: {
     SERVER_API_PREFIX: string;
   };
@@ -366,7 +966,6 @@ type ServerActionHandler<TConfig extends RequestConfigSchema = RequestConfigSche
  * This is NOT Server Request, but a specific type for actions.
  */
 interface ServerActionRequest<TConfig extends RequestConfigSchema> extends ServerRequest<TConfig> {}
-//# sourceMappingURL=$action.d.ts.map
 //#endregion
 //#region src/errors/HttpError.d.ts
 declare const isHttpError: (error: unknown, status?: number) => error is HttpErrorLike;
@@ -407,7 +1006,6 @@ declare const errorNameByStatus: Record<number, string>;
 interface HttpErrorLike extends Error {
   status: number;
 }
-//# sourceMappingURL=HttpError.d.ts.map
 //#endregion
 //#region src/descriptors/$route.d.ts
 /**
@@ -427,100 +1025,67 @@ declare class RouteDescriptor<TConfig extends RequestConfigSchema> extends Descr
   protected readonly serverRouterProvider: ServerRouterProvider;
   protected onInit(): void;
 }
-//# sourceMappingURL=$route.d.ts.map
 //#endregion
 //#region src/errors/BadRequestError.d.ts
 declare class BadRequestError extends HttpError {
   constructor(message?: string, cause?: unknown);
 }
-//# sourceMappingURL=BadRequestError.d.ts.map
 //#endregion
 //#region src/errors/ConflictError.d.ts
 declare class ConflictError extends HttpError {
   constructor(message?: string, cause?: unknown);
 }
-//# sourceMappingURL=ConflictError.d.ts.map
 //#endregion
 //#region src/errors/ForbiddenError.d.ts
 declare class ForbiddenError extends HttpError {
   constructor(message?: string, cause?: unknown);
 }
-//# sourceMappingURL=ForbiddenError.d.ts.map
 //#endregion
 //#region src/errors/NotFoundError.d.ts
 declare class NotFoundError extends HttpError {
   constructor(message?: string, cause?: unknown);
 }
-//# sourceMappingURL=NotFoundError.d.ts.map
 //#endregion
 //#region src/errors/UnauthorizedError.d.ts
 declare class UnauthorizedError extends HttpError {
   constructor(message?: string, cause?: unknown);
 }
-//# sourceMappingURL=UnauthorizedError.d.ts.map
 //#endregion
 //#region src/errors/ValidationError.d.ts
 declare class ValidationError extends HttpError {
   constructor(message?: string, cause?: unknown);
 }
-//# sourceMappingURL=ValidationError.d.ts.map
 //#endregion
 //#region src/helpers/isMultipart.d.ts
 declare const isMultipart: (options: {
   schema?: RequestConfigSchema;
+  requestBodyType?: string;
 }) => boolean;
-//# sourceMappingURL=isMultipart.d.ts.map
-//#endregion
-//#region src/schemas/apiLinksResponseSchema.d.ts
-declare const apiLinkSchema: _sinclair_typebox0.TObject<{
-  name: _sinclair_typebox0.TString;
-  path: _sinclair_typebox0.TString;
-  method: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  group: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  requestBodyType: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  service: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-}>;
-declare const apiLinksResponseSchema: _sinclair_typebox0.TObject<{
-  prefix: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  links: _sinclair_typebox0.TArray<_sinclair_typebox0.TObject<{
-    name: _sinclair_typebox0.TString;
-    path: _sinclair_typebox0.TString;
-    method: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-    group: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-    requestBodyType: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-    service: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  }>>;
-}>;
-type ApiLinksResponse = Static<typeof apiLinksResponseSchema>;
-type ApiLink = Static<typeof apiLinkSchema>;
-//# sourceMappingURL=apiLinksResponseSchema.d.ts.map
 //#endregion
 //#region src/schemas/errorSchema.d.ts
-declare const errorSchema: _sinclair_typebox25.TObject<{
-  error: _sinclair_typebox25.TString;
-  status: _sinclair_typebox25.TNumber;
-  message: _sinclair_typebox25.TString;
-  details: _sinclair_typebox25.TOptional<_sinclair_typebox25.TString>;
-  cause: _sinclair_typebox25.TOptional<_sinclair_typebox25.TObject<{
-    name: _sinclair_typebox25.TString;
-    message: _sinclair_typebox25.TString;
+declare const errorSchema: _sinclair_typebox0.TObject<{
+  error: _sinclair_typebox0.TString;
+  status: _sinclair_typebox0.TNumber;
+  message: _sinclair_typebox0.TString;
+  details: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  cause: _sinclair_typebox0.TOptional<_sinclair_typebox0.TObject<{
+    name: _sinclair_typebox0.TString;
+    message: _sinclair_typebox0.TString;
   }>>;
 }>;
-//# sourceMappingURL=errorSchema.d.ts.map
 //#endregion
 //#region src/schemas/okSchema.d.ts
-declare const okSchema: _sinclair_typebox35.TObject<{
-  ok: _sinclair_typebox35.TBoolean;
-  id: _sinclair_typebox35.TOptional<_sinclair_typebox35.TUnion<[_sinclair_typebox35.TString, _sinclair_typebox35.TInteger]>>;
-  count: _sinclair_typebox35.TOptional<_sinclair_typebox35.TNumber>;
+declare const okSchema: _sinclair_typebox0.TObject<{
+  ok: _sinclair_typebox0.TBoolean;
+  id: _sinclair_typebox0.TOptional<_sinclair_typebox0.TUnion<[_sinclair_typebox0.TString, _sinclair_typebox0.TInteger]>>;
+  count: _sinclair_typebox0.TOptional<_sinclair_typebox0.TNumber>;
 }>;
 type Ok = Static<typeof okSchema>;
-//# sourceMappingURL=okSchema.d.ts.map
 //#endregion
 //#region src/providers/NodeHttpServerProvider.d.ts
-declare const envSchema: _alepha_core11.TObject<{
-  SERVER_PORT: _alepha_core11.TNumber;
-  SERVER_HOST: _alepha_core11.TString;
+declare const envSchema: _alepha_core1.TObject<{
+  SERVER_PORT: _alepha_core1.TNumber;
+  SERVER_HOST: _alepha_core1.TString;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -528,33 +1093,32 @@ declare module "alepha" {
 declare class NodeHttpServerProvider extends ServerProvider {
   protected readonly alepha: Alepha;
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _alepha_core11.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly env: {
     SERVER_PORT: number;
     SERVER_HOST: string;
   };
   protected readonly router: ServerRouterProvider;
   protected readonly server: http0.Server<typeof IncomingMessage, typeof ServerResponse$1>;
-  protected readonly onNodeRequest: _alepha_core11.HookDescriptor<"node:request">;
+  protected readonly onNodeRequest: _alepha_core1.HookDescriptor<"node:request">;
   handle(req: IncomingMessage, res: ServerResponse$1): Promise<void>;
   createRouterRequest(req: IncomingMessage, res: ServerResponse$1, params?: Record<string, string>): ServerRawRequest;
   getProtocol(req: IncomingMessage): "http" | "https";
   get hostname(): string;
-  readonly start: _alepha_core11.HookDescriptor<"start">;
-  protected readonly stop: _alepha_core11.HookDescriptor<"stop">;
+  readonly start: _alepha_core1.HookDescriptor<"start">;
+  protected readonly stop: _alepha_core1.HookDescriptor<"stop">;
   protected listen(): Promise<void>;
   protected close(): Promise<void>;
 }
 //#endregion
 //#region src/providers/ServerLoggerProvider.d.ts
 declare class ServerLoggerProvider {
-  protected readonly log: _alepha_core6.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly alepha: Alepha;
-  readonly onRequest: _alepha_core6.HookDescriptor<"server:onRequest">;
-  readonly onError: _alepha_core6.HookDescriptor<"server:onError">;
-  readonly onResponse: _alepha_core6.HookDescriptor<"server:onResponse">;
+  readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
+  readonly onError: _alepha_core1.HookDescriptor<"server:onError">;
+  readonly onResponse: _alepha_core1.HookDescriptor<"server:onResponse">;
 }
-//# sourceMappingURL=ServerLoggerProvider.d.ts.map
 //#endregion
 //#region src/providers/ServerNotReadyProvider.d.ts
 /**
@@ -565,22 +1129,8 @@ declare class ServerLoggerProvider {
  * The response also includes a `Retry-After` header indicating that the client should retry after 5 seconds.
  */
 declare class ServerNotReadyProvider {
-  protected readonly alepha: Alepha;
-  readonly onRequest: _alepha_core10.HookDescriptor<"server:onRequest">;
-}
-//# sourceMappingURL=ServerNotReadyProvider.d.ts.map
-//#endregion
-//#region src/providers/ServerTimingProvider.d.ts
-type TimingMap = Record<string, [number, number]>;
-declare class ServerTimingProvider {
-  protected readonly log: _alepha_core1.Logger;
   protected readonly alepha: Alepha;
   readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
-  readonly onResponse: _alepha_core1.HookDescriptor<"server:onResponse">;
-  protected get handlerName(): string;
-  beginTiming(name: string): void;
-  endTiming(name: string): void;
-  protected setDuration(name: string, timing: TimingMap): void;
 }
 //#endregion
 //#region src/index.d.ts
@@ -648,9 +1198,7 @@ declare module "alepha" {
  * @see {@link $action}
  * @module alepha.server
  */
-declare const AlephaServer: _alepha_core0.Service<_alepha_core0.Module>;
-//# sourceMappingURL=index.d.ts.map
-
+declare const AlephaServer: _alepha_core1.Service<_alepha_core1.Module>;
 //#endregion
-export { $action, $route, ActionDescriptor, ActionDescriptorOptions, AlephaServer, ApiLink, ApiLinksResponse, BadRequestError, ClientRequestEntry, ClientRequestEntryContainer, ClientRequestOptions, ClientRequestResponse, ConflictError, FetchActionArgs, FetchOptions, FetchResponse, ForbiddenError, HttpAction, HttpClient, HttpClientPendingRequests, HttpError, HttpErrorLike, NodeHttpServerProvider, NotFoundError, Ok, RequestConfigSchema, ResponseBodyType, ResponseKind, RouteDescriptor, RouteDescriptorOptions, RouteMethod, ServerActionHandler, ServerActionRequest, ServerHandler, ServerLoggerProvider, ServerMiddlewareHandler, ServerNotReadyProvider, ServerProvider, ServerRawRequest, ServerReply, ServerRequest, ServerRequestConfig, ServerRequestConfigEntry, ServerResponse, ServerResponseBody, ServerRoute, ServerRouteMatcher, ServerRouterProvider, ServerTimingProvider, UnauthorizedError, ValidationError, apiLinkSchema, apiLinksResponseSchema, errorNameByStatus, errorSchema, isHttpError, isMultipart, okSchema, routeMethods };
+export { $action, $route, ActionDescriptor, ActionDescriptorOptions, AlephaServer, BadRequestError, ClientRequestEntry, ClientRequestEntryContainer, ClientRequestOptions, ClientRequestResponse, ConflictError, FetchActionArgs, FetchOptions, FetchResponse, ForbiddenError, HttpAction, HttpClient, HttpClientPendingRequests, HttpError, HttpErrorLike, NodeHttpServerProvider, NotFoundError, Ok, RequestConfigSchema, ResponseBodyType, ResponseKind, RouteDescriptor, RouteDescriptorOptions, RouteMethod, ServerActionHandler, ServerActionRequest, ServerHandler, ServerLoggerProvider, ServerMiddlewareHandler, ServerNotReadyProvider, ServerProvider, ServerRawRequest, ServerReply, ServerRequest, ServerRequestConfig, ServerRequestConfigEntry, ServerResponse, ServerResponseBody, ServerRoute, ServerRouteMatcher, ServerRouteRequestHandler, ServerRouterProvider, ServerTimingProvider, UnauthorizedError, ValidationError, errorNameByStatus, errorSchema, isHttpError, isMultipart, okSchema, routeMethods };
 //# sourceMappingURL=index.d.ts.map