@wild-framework/http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @wild-framework/http
+
+Express integration, routing, and error handling for [Wild Framework](https://github.com/your-org/wild-framework).
+
+## Install
+
+```bash
+pnpm add @wild-framework/http
+```
+
+## Usage
+
+```ts
+import { Router, action } from "@wild-framework/http";
+
+const router = app.resolve(Router);
+
+router.get("/users", action(UserController, "index"));
+router.post("/users", CreateUserRequest, action(UserController, "store"));
+router.use(express.json());
+```
+
+Throwing an `HttpException` (e.g. `NotFoundException`) produces a structured JSON error response.
+
+## License
+
+MIT

package/dist/action.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tagged handler produced by `action(ControllerClass, "method")`.
+ *
+ * At request time, the Router resolves the controller from the container
+ * and calls the named method.
+ */
+export interface ActionHandler {
+    /** The controller class to resolve from the container. */
+    readonly controller: abstract new (...args: any[]) => unknown;
+    /** The method name to call on the resolved instance. */
+    readonly method: string;
+}
+/**
+ * Mark a controller method for lazy resolution.
+ *
+ * The Router detects `ActionHandler` objects and resolves the controller
+ * from the container at request time.
+ *
+ * @example
+ * router.get("/users", action(UserController, "index"));
+ */
+export declare function action<T, K extends keyof T>(controller: abstract new (...args: any[]) => T, method: K & string): ActionHandler;
+//# sourceMappingURL=action.d.ts.map

package/dist/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;IAC9D,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EACvC,UAAU,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC9C,MAAM,EAAE,CAAC,GAAG,MAAM,GACnB,aAAa,CAEf"}

package/dist/action.js

@@ -0,0 +1,13 @@
+/**
+ * Mark a controller method for lazy resolution.
+ *
+ * The Router detects `ActionHandler` objects and resolves the controller
+ * from the container at request time.
+ *
+ * @example
+ * router.get("/users", action(UserController, "index"));
+ */
+export function action(controller, method) {
+    return { controller, method };
+}
+//# sourceMappingURL=action.js.map

package/dist/action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAClB,UAA8C,EAC9C,MAAkB;IAElB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAClC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,49 @@
+import type { ZodError } from "zod";
+/**
+ * Base HTTP exception. Produces a structured JSON error response.
+ */
+export declare class HttpException extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+    toJSON(): {
+        error: string;
+        message: string;
+        statusCode: number;
+    };
+    private getStatusText;
+}
+/**
+ * 404 — resource not found.
+ */
+export declare class NotFoundException extends HttpException {
+    constructor(message?: string);
+}
+/**
+ * 422 — validation failed.
+ */
+export declare class ValidationException extends HttpException {
+    readonly errors: ZodError;
+    constructor(error: ZodError);
+    toJSON(): {
+        errors: {
+            path: string;
+            message: string;
+        }[];
+        error: string;
+        message: string;
+        statusCode: number;
+    };
+}
+/**
+ * 403 — forbidden.
+ */
+export declare class ForbiddenException extends HttpException {
+    constructor(message?: string);
+}
+/**
+ * 401 — unauthorized.
+ */
+export declare class UnauthorizedException extends HttpException {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,KAAK,CAAC;AAE/C;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAEhB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM,EAClC,OAAO,EAAE,MAAM;IAMnB,MAAM;;;;;IAQN,OAAO,CAAC,aAAa;CAWxB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;gBACpC,OAAO,SAAuB;CAI7C;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IAClD,SAAgB,MAAM,EAAE,QAAQ,CAAC;gBAErB,KAAK,EAAE,QAAQ;IAM3B,MAAM;;;;;;;;;CAST;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACrC,OAAO,SAAc;CAIpC;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;gBACxC,OAAO,SAAiB;CAIvC"}

package/dist/errors.js

@@ -0,0 +1,77 @@
+/**
+ * Base HTTP exception. Produces a structured JSON error response.
+ */
+export class HttpException extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "HttpException";
+    }
+    toJSON() {
+        return {
+            error: this.getStatusText(),
+            message: this.message,
+            statusCode: this.statusCode,
+        };
+    }
+    getStatusText() {
+        const map = {
+            400: "Bad Request",
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            422: "Unprocessable Entity",
+            500: "Internal Server Error",
+        };
+        return map[this.statusCode] ?? "Error";
+    }
+}
+/**
+ * 404 — resource not found.
+ */
+export class NotFoundException extends HttpException {
+    constructor(message = "Resource not found") {
+        super(404, message);
+        this.name = "NotFoundException";
+    }
+}
+/**
+ * 422 — validation failed.
+ */
+export class ValidationException extends HttpException {
+    errors;
+    constructor(error) {
+        super(422, "Validation failed");
+        this.name = "ValidationException";
+        this.errors = error;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            errors: this.errors.issues.map((i) => ({
+                path: i.path.join("."),
+                message: i.message,
+            })),
+        };
+    }
+}
+/**
+ * 403 — forbidden.
+ */
+export class ForbiddenException extends HttpException {
+    constructor(message = "Forbidden") {
+        super(403, message);
+        this.name = "ForbiddenException";
+    }
+}
+/**
+ * 401 — unauthorized.
+ */
+export class UnauthorizedException extends HttpException {
+    constructor(message = "Unauthorized") {
+        super(401, message);
+        this.name = "UnauthorizedException";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAEhB;IADpB,YACoB,UAAkB,EAClC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,eAAU,GAAV,UAAU,CAAQ;QAIlC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAChC,CAAC;IAED,MAAM;QACF,OAAO;YACH,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC9B,CAAC;IACN,CAAC;IAEO,aAAa;QACjB,MAAM,GAAG,GAA2B;YAChC,GAAG,EAAE,aAAa;YAClB,GAAG,EAAE,cAAc;YACnB,GAAG,EAAE,WAAW;YAChB,GAAG,EAAE,WAAW;YAChB,GAAG,EAAE,sBAAsB;YAC3B,GAAG,EAAE,uBAAuB;SAC/B,CAAC;QACF,OAAO,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC;IAC3C,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAChD,YAAY,OAAO,GAAG,oBAAoB;QACtC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACpC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAClC,MAAM,CAAW;IAEjC,YAAY,KAAe;QACvB,KAAK,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,MAAM;QACF,OAAO;YACH,GAAG,KAAK,CAAC,MAAM,EAAE;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACnC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBACtB,OAAO,EAAE,CAAC,CAAC,OAAO;aACrB,CAAC,CAAC;SACN,CAAC;IACN,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACjD,YAAY,OAAO,GAAG,WAAW;QAC7B,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACrC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACpD,YAAY,OAAO,GAAG,cAAc;QAChC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACxC,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { action } from "./action.js";
+export type { ActionHandler } from "./action.js";
+export { ForbiddenException, HttpException, NotFoundException, UnauthorizedException, ValidationException, } from "./errors.js";
+export { HttpProvider } from "./provider.js";
+export { Router } from "./router.js";
+export { ExpressServer, createErrorHandler } from "./server.js";
+export type { RouteHandler } from "./wrap.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACH,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { action } from "./action.js";
+export { ForbiddenException, HttpException, NotFoundException, UnauthorizedException, ValidationException, } from "./errors.js";
+export { HttpProvider } from "./provider.js";
+export { Router } from "./router.js";
+export { ExpressServer, createErrorHandler } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACH,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,14 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers the HTTP layer with the application.
+ *
+ * - `register()`: creates Express app, Router, ExpressServer. Binds Router
+ *   into the container and calls `app.setServer()`.
+ * - `boot()`: registers the global error handler middleware on the Express app.
+ */
+export declare class HttpProvider implements Provider {
+    private expressApp;
+    register(app: Application): void;
+    boot(_app: Application): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMlE;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,QAAQ;IACzC,OAAO,CAAC,UAAU,CAAwB;IAE1C,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAkBhC,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;CAKhC"}

package/dist/provider.js

@@ -0,0 +1,33 @@
+import { Container } from "@wild-framework/container";
+import express, {} from "express";
+import { Router } from "./router.js";
+import { ExpressServer, createErrorHandler } from "./server.js";
+/**
+ * Registers the HTTP layer with the application.
+ *
+ * - `register()`: creates Express app, Router, ExpressServer. Binds Router
+ *   into the container and calls `app.setServer()`.
+ * - `boot()`: registers the global error handler middleware on the Express app.
+ */
+export class HttpProvider {
+    expressApp = null;
+    register(app) {
+        const container = app.resolve(Container);
+        // Express app
+        this.expressApp = express();
+        // Router — bound into container so providers can add routes
+        const router = new Router(container);
+        container.singleton(Router, () => router);
+        // Mount router on Express (routes defined by providers during register())
+        this.expressApp.use(router._getExpressRouter());
+        // Server — registered on app for app.listen()
+        const server = new ExpressServer(this.expressApp);
+        app.setServer(server);
+    }
+    boot(_app) {
+        // Global error handler — must be the last middleware on the Express app.
+        // Added during boot phase 2, after all routes have been registered.
+        this.expressApp.use(createErrorHandler());
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,OAAO,EAAE,EAAgB,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACb,UAAU,GAAmB,IAAI,CAAC;IAE1C,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEzC,cAAc;QACd,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,CAAC;QAE5B,4DAA4D;QAC5D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;QACrC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QAE1C,0EAA0E;QAC1E,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC;QAEhD,8CAA8C;QAC9C,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClD,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,CAAC,IAAiB;QAClB,yEAAyE;QACzE,oEAAoE;QACpE,IAAI,CAAC,UAAW,CAAC,GAAG,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC/C,CAAC;CACJ"}

package/dist/router.d.ts

@@ -0,0 +1,30 @@
+import { Router as ExpressRouter, type RequestHandler } from "express";
+import { Container } from "@wild-framework/container";
+import { type RouteHandler } from "./wrap.js";
+/**
+ * Wild Framework Router.
+ *
+ * Wraps Express routing with controller resolution and validation.
+ * Routes are defined using `action()` for controller methods and
+ * validator classes with Zod schemas.
+ *
+ * Resolved from the container: `app.resolve(Router)`.
+ */
+export declare class Router {
+    private container;
+    private expressRouter;
+    constructor(container: Container);
+    get(path: string, ...handlers: RouteHandler[]): void;
+    post(path: string, ...handlers: RouteHandler[]): void;
+    put(path: string, ...handlers: RouteHandler[]): void;
+    patch(path: string, ...handlers: RouteHandler[]): void;
+    delete(path: string, ...handlers: RouteHandler[]): void;
+    /**
+     * Register global middleware on the router.
+     */
+    use(...handlers: RequestHandler[]): void;
+    /** @internal — get the underlying Express router. */
+    _getExpressRouter(): ExpressRouter;
+    private wrapAll;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;GAQG;AACH,qBAAa,MAAM;IAGH,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,aAAa,CAAgB;gBAEjB,SAAS,EAAE,SAAS;IAQxC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAIpD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAIrD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAIpD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAItD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAQvD;;OAEG;IACH,GAAG,CAAC,GAAG,QAAQ,EAAE,cAAc,EAAE,GAAG,IAAI;IAQxC,qDAAqD;IACrD,iBAAiB,IAAI,aAAa;IAIlC,OAAO,CAAC,OAAO;CAGlB"}

package/dist/router.js

@@ -0,0 +1,58 @@
+import { Router as ExpressRouter } from "express";
+import { Container } from "@wild-framework/container";
+import { wrapHandler } from "./wrap.js";
+/**
+ * Wild Framework Router.
+ *
+ * Wraps Express routing with controller resolution and validation.
+ * Routes are defined using `action()` for controller methods and
+ * validator classes with Zod schemas.
+ *
+ * Resolved from the container: `app.resolve(Router)`.
+ */
+export class Router {
+    container;
+    expressRouter;
+    constructor(container) {
+        this.container = container;
+        this.expressRouter = ExpressRouter();
+    }
+    // -------------------------------------------------------------------
+    // HTTP methods
+    // -------------------------------------------------------------------
+    get(path, ...handlers) {
+        this.expressRouter.get(path, ...this.wrapAll(handlers));
+    }
+    post(path, ...handlers) {
+        this.expressRouter.post(path, ...this.wrapAll(handlers));
+    }
+    put(path, ...handlers) {
+        this.expressRouter.put(path, ...this.wrapAll(handlers));
+    }
+    patch(path, ...handlers) {
+        this.expressRouter.patch(path, ...this.wrapAll(handlers));
+    }
+    delete(path, ...handlers) {
+        this.expressRouter.delete(path, ...this.wrapAll(handlers));
+    }
+    // -------------------------------------------------------------------
+    // Middleware
+    // -------------------------------------------------------------------
+    /**
+     * Register global middleware on the router.
+     */
+    use(...handlers) {
+        this.expressRouter.use(...handlers);
+    }
+    // -------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------
+    /** @internal — get the underlying Express router. */
+    _getExpressRouter() {
+        return this.expressRouter;
+    }
+    wrapAll(handlers) {
+        return handlers.map((h) => wrapHandler(h, this.container));
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,aAAa,EAAuB,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,OAAO,MAAM;IAGK;IAFZ,aAAa,CAAgB;IAErC,YAAoB,SAAoB;QAApB,cAAS,GAAT,SAAS,CAAW;QACpC,IAAI,CAAC,aAAa,GAAG,aAAa,EAAE,CAAC;IACzC,CAAC;IAED,sEAAsE;IACtE,eAAe;IACf,sEAAsE;IAEtE,GAAG,CAAC,IAAY,EAAE,GAAG,QAAwB;QACzC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI,CAAC,IAAY,EAAE,GAAG,QAAwB;QAC1C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,GAAG,CAAC,IAAY,EAAE,GAAG,QAAwB;QACzC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,IAAY,EAAE,GAAG,QAAwB;QAC3C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,GAAG,QAAwB;QAC5C,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,sEAAsE;IACtE,aAAa;IACb,sEAAsE;IAEtE;;OAEG;IACH,GAAG,CAAC,GAAG,QAA0B;QAC7B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,sEAAsE;IACtE,WAAW;IACX,sEAAsE;IAEtE,qDAAqD;IACrD,iBAAiB;QACb,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;IAEO,OAAO,CAAC,QAAwB;QACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAqB,CAAC;IACnF,CAAC;CACJ"}

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+import type { Server as CoreServer } from "@wild-framework/core";
+import express, { type Express } from "express";
+/**
+ * Express-backed implementation of core's `Server` interface.
+ *
+ * Created by `HttpProvider` and registered via `app.setServer()`.
+ */
+export declare class ExpressServer implements CoreServer {
+    private app;
+    private server;
+    constructor(app: Express);
+    listen(port: number): Promise<void>;
+    shutdown(): Promise<void>;
+    /** @internal */
+    _getExpressApp(): Express;
+}
+/**
+ * Create a global error handler middleware for Express.
+ *
+ * Formats `HttpException` instances as structured JSON.
+ * Unexpected errors return 500 with a generic message.
+ */
+export declare function createErrorHandler(): express.ErrorRequestHandler;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,OAAO,EAAE,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAIhD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC5C,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,MAAM,CAA2B;gBAE7B,GAAG,EAAE,OAAO;IAIlB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B,gBAAgB;IAChB,cAAc,IAAI,OAAO;CAG5B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAAC,mBAAmB,CAehE"}

package/dist/server.js

@@ -0,0 +1,54 @@
+import express, {} from "express";
+import { HttpException } from "./errors.js";
+/**
+ * Express-backed implementation of core's `Server` interface.
+ *
+ * Created by `HttpProvider` and registered via `app.setServer()`.
+ */
+export class ExpressServer {
+    app;
+    server = null;
+    constructor(app) {
+        this.app = app;
+    }
+    async listen(port) {
+        return new Promise((resolve, reject) => {
+            this.server = this.app.listen(port, () => resolve());
+            this.server.on("error", reject);
+        });
+    }
+    async shutdown() {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                return resolve();
+            }
+            this.server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+    /** @internal */
+    _getExpressApp() {
+        return this.app;
+    }
+}
+/**
+ * Create a global error handler middleware for Express.
+ *
+ * Formats `HttpException` instances as structured JSON.
+ * Unexpected errors return 500 with a generic message.
+ */
+export function createErrorHandler() {
+    return (err, _req, res, _next) => {
+        if (err instanceof HttpException) {
+            res.status(err.statusCode).json(err.toJSON());
+            return;
+        }
+        // Unexpected error — log and return generic 500
+        console.error("[wild/http] Unhandled error:", err);
+        res.status(500).json({
+            error: "Internal Server Error",
+            message: "An unexpected error occurred.",
+            statusCode: 500,
+        });
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,EAAE,EAAgB,MAAM,SAAS,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACd,GAAG,CAAU;IACb,MAAM,GAAsB,IAAI,CAAC;IAEzC,YAAY,GAAY;QACpB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACrB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YACrD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACP,CAAC;IAED,KAAK,CAAC,QAAQ;QACV,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACf,OAAO,OAAO,EAAE,CAAC;YACrB,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;IACP,CAAC;IAED,gBAAgB;IAChB,cAAc;QACV,OAAO,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;CACJ;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAC9B,OAAO,CAAC,GAAY,EAAE,IAAqB,EAAE,GAAqB,EAAE,KAA2B,EAAE,EAAE;QAC/F,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;YAC/B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC9C,OAAO;QACX,CAAC;QAED,gDAAgD;QAChD,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;QACnD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACjB,KAAK,EAAE,uBAAuB;YAC9B,OAAO,EAAE,+BAA+B;YACxC,UAAU,EAAE,GAAG;SAClB,CAAC,CAAC;IACP,CAAC,CAAC;AACN,CAAC"}

package/dist/wrap.d.ts

@@ -0,0 +1,27 @@
+import type { Request, Response, NextFunction } from "express";
+import type { ActionHandler } from "./action.js";
+/**
+ * Express request handler type (after wrapping).
+ */
+type ExpressHandler = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * Any value that can be used as a route handler — raw middleware,
+ * ActionHandler, or a validator class (must have `static schema`).
+ */
+export type RouteHandler = ExpressHandler | ActionHandler | (new (...args: any[]) => unknown);
+/**
+ * Container-like resolver used by wrapped handlers.
+ */
+interface Resolver {
+    resolve<T>(token: unknown): T;
+}
+/**
+ * Wrap a route handler for use with Express.
+ *
+ * - `ActionHandler` → resolved controller + method call
+ * - validator class (has `schema`) → validates `req.body`
+ * - plain function → passed through directly
+ */
+export declare function wrapHandler(handler: RouteHandler, container: Resolver): ExpressHandler;
+export {};
+//# sourceMappingURL=wrap.d.ts.map

package/dist/wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../src/wrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;GAEG;AACH,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhG;;;GAGG;AACH,MAAM,MAAM,YAAY,GAClB,cAAc,GACd,aAAa,GACb,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC;AAExC;;GAEG;AACH,UAAU,QAAQ;IACd,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,GAAG,cAAc,CAatF"}

package/dist/wrap.js

@@ -0,0 +1,64 @@
+import { ValidationException } from "./errors.js";
+/**
+ * Wrap a route handler for use with Express.
+ *
+ * - `ActionHandler` → resolved controller + method call
+ * - validator class (has `schema`) → validates `req.body`
+ * - plain function → passed through directly
+ */
+export function wrapHandler(handler, container) {
+    // Validator class — detect by checking if it's a constructor with schema
+    if (isValidatorClass(handler)) {
+        return wrapValidator(handler);
+    }
+    // ActionHandler — controller method reference
+    if (isActionHandler(handler)) {
+        return wrapAction(handler, container);
+    }
+    // Plain Express handler
+    return handler;
+}
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+function isValidatorClass(h) {
+    return (typeof h === "function" &&
+        "schema" in h);
+}
+function isActionHandler(h) {
+    return (typeof h === "object" &&
+        h !== null &&
+        "controller" in h &&
+        "method" in h);
+}
+// ---------------------------------------------------------------------------
+// Wrappers
+// ---------------------------------------------------------------------------
+function wrapValidator(ValidatorClass) {
+    // schema is a static property on the class
+    const schema = ValidatorClass.schema;
+    return (req, _res, next) => {
+        const result = schema.safeParse(req.body);
+        if (!result.success) {
+            return next(new ValidationException(result.error));
+        }
+        req.body = result.data;
+        next();
+    };
+}
+function wrapAction(action, container) {
+    return async (req, res, next) => {
+        try {
+            const instance = container.resolve(action.controller);
+            const method = instance[action.method];
+            if (typeof method !== "function") {
+                throw new Error(`Method "${action.method}" not found on controller "${action.controller.name}".`);
+            }
+            await method.call(instance, req, res, next);
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+//# sourceMappingURL=wrap.js.map

package/dist/wrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.js","sourceRoot":"","sources":["../src/wrap.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAwBlD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAqB,EAAE,SAAmB;IAClE,yEAAyE;IACzE,IAAI,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,8CAA8C;IAC9C,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,wBAAwB;IACxB,OAAO,OAAyB,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,SAAS,gBAAgB,CAAC,CAAe;IACrC,OAAO,CACH,OAAO,CAAC,KAAK,UAAU;QACvB,QAAQ,IAAI,CAAC,CAChB,CAAC;AACN,CAAC;AAED,SAAS,eAAe,CAAC,CAAe;IACpC,OAAO,CACH,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,YAAY,IAAI,CAAC;QACjB,QAAQ,IAAI,CAAC,CAChB,CAAC;AACN,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,SAAS,aAAa,CAClB,cAA6D;IAE7D,2CAA2C;IAC3C,MAAM,MAAM,GAAI,cAAmD,CAAC,MAAM,CAAC;IAE3E,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE1C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACvD,CAAC;QAED,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACvB,IAAI,EAAE,CAAC;IACX,CAAC,CAAC;AACN,CAAC;AAED,SAAS,UAAU,CAAC,MAAqB,EAAE,SAAmB;IAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAA6B,CAAC;YAClF,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAEvC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC/B,MAAM,IAAI,KAAK,CACX,WAAW,MAAM,CAAC,MAAM,8BAA8B,MAAM,CAAC,UAAU,CAAC,IAAI,IAAI,CACnF,CAAC;YACN,CAAC;YAED,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC;IACL,CAAC,CAAC;AACN,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@wild-framework/http",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "Express integration, routing, and error handling for Wild Framework.",
+  "keywords": [
+    "wild",
+    "framework",
+    "http",
+    "express",
+    "router"
+  ],
+  "dependencies": {
+    "express": "^5.1.0",
+    "@wild-framework/core": "0.1.0",
+    "@wild-framework/container": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}