@terreno/api 0.0.17 → 0.1.0

package/dist/githubAuth.test.js

@@ -0,0 +1,351 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var mongoose_1 = __importStar(require("mongoose"));
+var passport_local_mongoose_1 = __importDefault(require("passport-local-mongoose"));
+var supertest_1 = __importDefault(require("supertest"));
+var expressServer_1 = require("./expressServer");
+var githubAuth_1 = require("./githubAuth");
+var logger_1 = require("./logger");
+var plugins_1 = require("./plugins");
+// Create schema for GitHub-enabled user
+var testUserSchema = new mongoose_1.Schema({
+    admin: { default: false, description: "Whether the user has admin privileges", type: Boolean },
+    name: { description: "The user's display name", type: String },
+    username: { description: "The user's username", type: String },
+});
+testUserSchema.plugin(passport_local_mongoose_1.default, {
+    attemptsField: "attempts",
+    interval: 1,
+    limitAttempts: true,
+    maxAttempts: 3,
+    maxInterval: 1,
+    usernameCaseInsensitive: true,
+    usernameField: "email",
+});
+testUserSchema.plugin(plugins_1.createdUpdatedPlugin);
+testUserSchema.plugin(plugins_1.isDisabledPlugin);
+testUserSchema.plugin(githubAuth_1.githubUserPlugin);
+// Get or create model to avoid model redefinition errors
+var GitHubTestUserModel = mongoose_1.default.models.GitHubTestUser || (0, mongoose_1.model)("GitHubTestUser", testUserSchema);
+// Connect to database before tests
+var connectDb = function () { return __awaiter(void 0, void 0, void 0, function () {
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                if (!(mongoose_1.default.connection.readyState === 0)) return [3 /*break*/, 2];
+                return [4 /*yield*/, mongoose_1.default
+                        .connect("mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000")
+                        .catch(logger_1.logger.catch)];
+            case 1:
+                _a.sent();
+                _a.label = 2;
+            case 2:
+                process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+                process.env.TOKEN_SECRET = "secret";
+                process.env.TOKEN_EXPIRES_IN = "30m";
+                process.env.TOKEN_ISSUER = "example.com";
+                process.env.SESSION_SECRET = "session";
+                return [2 /*return*/];
+        }
+    });
+}); };
+(0, bun_test_1.describe)("githubUserPlugin", function () {
+    (0, bun_test_1.it)("adds GitHub fields to schema", function () {
+        var paths = testUserSchema.paths;
+        (0, bun_test_1.expect)(paths.githubId).toBeDefined();
+        (0, bun_test_1.expect)(paths.githubUsername).toBeDefined();
+        (0, bun_test_1.expect)(paths.githubProfileUrl).toBeDefined();
+        (0, bun_test_1.expect)(paths.githubAvatarUrl).toBeDefined();
+    });
+    (0, bun_test_1.it)("githubId is indexed and sparse", function () {
+        var githubIdPath = testUserSchema.path("githubId");
+        (0, bun_test_1.expect)(githubIdPath.options.index).toBe(true);
+        (0, bun_test_1.expect)(githubIdPath.options.sparse).toBe(true);
+        (0, bun_test_1.expect)(githubIdPath.options.unique).toBe(true);
+    });
+});
+(0, bun_test_1.describe)("GitHub auth routes", function () {
+    var app;
+    var agent;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        function addRoutes(router) {
+            router.get("/test", function (_req, res) { return res.json({ ok: true }); });
+        }
+        var testUser;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, bun_test_1.setSystemTime)();
+                    return [4 /*yield*/, connectDb()];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, GitHubTestUserModel.deleteMany({})];
+                case 2:
+                    _a.sent();
+                    return [4 /*yield*/, GitHubTestUserModel.create({
+                            admin: false,
+                            email: "test@example.com",
+                            name: "Test User",
+                        })];
+                case 3:
+                    testUser = _a.sent();
+                    return [4 /*yield*/, testUser.setPassword("password123")];
+                case 4:
+                    _a.sent();
+                    return [4 /*yield*/, testUser.save()];
+                case 5:
+                    _a.sent();
+                    app = (0, expressServer_1.setupServer)({
+                        addRoutes: addRoutes,
+                        githubAuth: {
+                            allowAccountLinking: true,
+                            callbackURL: "http://localhost:9000/auth/github/callback",
+                            clientId: "test-client-id",
+                            clientSecret: "test-client-secret",
+                        },
+                        skipListen: true,
+                        userModel: GitHubTestUserModel,
+                    });
+                    agent = supertest_1.default.agent(app);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            (0, bun_test_1.setSystemTime)();
+            return [2 /*return*/];
+        });
+    }); });
+    (0, bun_test_1.it)("GET /auth/github redirects to GitHub OAuth", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent.get("/auth/github").expect(302)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.headers.location).toContain("github.com");
+                    (0, bun_test_1.expect)(res.headers.location).toContain("client_id=test-client-id");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("GET /auth/github/failure returns 401", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent.get("/auth/github/failure").expect(401)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.message).toBe("GitHub authentication failed");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("DELETE /auth/github/unlink requires authentication", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent.delete("/auth/github/unlink").expect(401)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body).toBeDefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("DELETE /auth/github/unlink works when authenticated with password", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var loginRes, user, res, updatedUser;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent
+                        .post("/auth/login")
+                        .send({ email: "test@example.com", password: "password123" })
+                        .expect(200)];
+                case 1:
+                    loginRes = _a.sent();
+                    return [4 /*yield*/, GitHubTestUserModel.findOne({ email: "test@example.com" })];
+                case 2:
+                    user = _a.sent();
+                    if (!user) return [3 /*break*/, 4];
+                    user.githubId = "99999";
+                    user.githubUsername = "testghuser";
+                    return [4 /*yield*/, user.save()];
+                case 3:
+                    _a.sent();
+                    _a.label = 4;
+                case 4: return [4 /*yield*/, agent
+                        .delete("/auth/github/unlink")
+                        .set("authorization", "Bearer ".concat(loginRes.body.data.token))
+                        .expect(200)];
+                case 5:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.data.message).toBe("GitHub account unlinked successfully");
+                    return [4 /*yield*/, GitHubTestUserModel.findOne({ email: "test@example.com" })];
+                case 6:
+                    updatedUser = _a.sent();
+                    (0, bun_test_1.expect)(updatedUser.githubId).toBeUndefined();
+                    (0, bun_test_1.expect)(updatedUser.githubUsername).toBeUndefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("user can have both password and GitHub auth", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var user, res, updatedUser;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, GitHubTestUserModel.findOne({ email: "test@example.com" })];
+                case 1:
+                    user = _a.sent();
+                    (0, bun_test_1.expect)(user).toBeDefined();
+                    if (!user) {
+                        return [2 /*return*/];
+                    }
+                    // Link GitHub
+                    user.githubId = "88888";
+                    user.githubUsername = "linkeduser";
+                    return [4 /*yield*/, user.save()];
+                case 2:
+                    _a.sent();
+                    return [4 /*yield*/, agent
+                            .post("/auth/login")
+                            .send({ email: "test@example.com", password: "password123" })
+                            .expect(200)];
+                case 3:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.data.token).toBeDefined();
+                    return [4 /*yield*/, GitHubTestUserModel.findOne({ email: "test@example.com" })];
+                case 4:
+                    updatedUser = _a.sent();
+                    (0, bun_test_1.expect)(updatedUser).toBeDefined();
+                    (0, bun_test_1.expect)(updatedUser.githubId).toBe("88888");
+                    (0, bun_test_1.expect)(updatedUser.githubUsername).toBe("linkeduser");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("GitHub auth disabled", function () {
+    var app;
+    var agent;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        function addRoutes(router) {
+            router.get("/test", function (_req, res) { return res.json({ ok: true }); });
+        }
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, bun_test_1.setSystemTime)();
+                    return [4 /*yield*/, connectDb()];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, GitHubTestUserModel.deleteMany({})];
+                case 2:
+                    _a.sent();
+                    // Setup server WITHOUT GitHub auth
+                    app = (0, expressServer_1.setupServer)({
+                        addRoutes: addRoutes,
+                        skipListen: true,
+                        userModel: GitHubTestUserModel,
+                    });
+                    agent = supertest_1.default.agent(app);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            (0, bun_test_1.setSystemTime)();
+            return [2 /*return*/];
+        });
+    }); });
+    (0, bun_test_1.it)("GitHub routes are not available when githubAuth is not configured", function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, agent.get("/auth/github").expect(404)];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, agent.get("/auth/github/callback").expect(404)];
+                case 2:
+                    _a.sent();
+                    return [4 /*yield*/, agent.delete("/auth/github/unlink").expect(404)];
+                case 3:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});

package/dist/index.d.ts

@@ -2,13 +2,16 @@ export * from "./api";
 export * from "./auth";
 export * from "./errors";
 export * from "./expressServer";
+export * from "./githubAuth";
 export * from "./logger";
 export * from "./middleware";
 export * from "./notifiers";
 export * from "./openApiBuilder";
 export * from "./openApiEtag";
+export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./terrenoPlugin";
 export * from "./transformers";
 export * from "./utils";

package/dist/index.js

@@ -18,13 +18,16 @@ __exportStar(require("./api"), exports);
 __exportStar(require("./auth"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./expressServer"), exports);
+__exportStar(require("./githubAuth"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./middleware"), exports);
 __exportStar(require("./notifiers"), exports);
 __exportStar(require("./openApiBuilder"), exports);
 __exportStar(require("./openApiEtag"), exports);
+__exportStar(require("./openApiValidator"), exports);
 __exportStar(require("./permissions"), exports);
 __exportStar(require("./plugins"), exports);
 __exportStar(require("./populate"), exports);
+__exportStar(require("./terrenoPlugin"), exports);
 __exportStar(require("./transformers"), exports);
 __exportStar(require("./utils"), exports);

package/dist/logger.js

@@ -87,7 +87,7 @@ exports.logger = exports.winstonLogger = void 0;
 exports.setupLogging = setupLogging;
 var node_fs_1 = __importDefault(require("node:fs"));
 var node_util_1 = require("node:util");
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var winston_1 = __importDefault(require("winston"));
 function isPrimitive(val) {
     return val === null || (typeof val !== "object" && typeof val !== "function");

package/dist/middleware.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sentryAppVersionMiddleware = sentryAppVersionMiddleware;
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 /**
  * Express middleware that captures the app version from the request header
  * and adds it as a tag to the current Sentry scope.

package/dist/notifiers/googleChatNotifier.js

@@ -73,7 +73,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendToGoogleChat = sendToGoogleChat;
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
 var errors_1 = require("../errors");
 var logger_1 = require("../logger");

package/dist/notifiers/googleChatNotifier.test.js

@@ -100,7 +100,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
 var googleChatNotifier_1 = require("./googleChatNotifier");
 (0, bun_test_1.describe)("sendToGoogleChat", function () {

package/dist/notifiers/slackNotifier.js

@@ -73,7 +73,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendToSlack = sendToSlack;
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
 var errors_1 = require("../errors");
 var logger_1 = require("../logger");

package/dist/notifiers/slackNotifier.test.js

@@ -100,7 +100,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
 var slackNotifier_1 = require("./slackNotifier");
 (0, bun_test_1.describe)("sendToSlack", function () {

package/dist/notifiers/zoomNotifier.js

@@ -73,7 +73,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendToZoom = sendToZoom;
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
 var errors_1 = require("../errors");
 var logger_1 = require("../logger");

package/dist/notifiers/zoomNotifier.test.js

@@ -100,7 +100,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
-var Sentry = __importStar(require("@sentry/node"));
+var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
 var zoomNotifier_1 = require("./zoomNotifier");
 (0, bun_test_1.describe)("sendToZoom", function () {

package/dist/openApi.test.js

@@ -273,13 +273,13 @@ function addRoutes(router, options) {
                     // Ensure that a Number query field supports gt/gte/lt/lte and just a Number
                     (0, bun_test_1.expect)(foodQuery.schema).toEqual({
                         oneOf: [
-                            { type: "number" },
+                            { description: "Number of calories in the food", type: "number" },
                             {
                                 properties: {
-                                    $gt: { type: "number" },
-                                    $gte: { type: "number" },
-                                    $lt: { type: "number" },
-                                    $lte: { type: "number" },
+                                    $gt: { description: "Number of calories in the food", type: "number" },
+                                    $gte: { description: "Number of calories in the food", type: "number" },
+                                    $lt: { description: "Number of calories in the food", type: "number" },
+                                    $lte: { description: "Number of calories in the food", type: "number" },
                                 },
                                 type: "object",
                             },
@@ -393,6 +393,7 @@ function addRoutesPopulate(router, options) {
                                 type: "string",
                             },
                             name: {
+                                description: "The user's display name",
                                 type: "string",
                             },
                         },
@@ -406,12 +407,14 @@ function addRoutesPopulate(router, options) {
                         type: "array",
                     });
                     (0, bun_test_1.expect)(properties.likesIds).toEqual({
+                        description: "User likes for this food",
                         items: {
                             properties: {
                                 _id: {
                                     type: "string",
                                 },
                                 likes: {
+                                    description: "Whether the user liked the item",
                                     type: "boolean",
                                 },
                                 userId: {

package/dist/openApiBuilder.d.ts

@@ -153,6 +153,20 @@ export type OpenApiResponse = {
         };
     };
 };
+/**
+ * Result from building OpenAPI middleware with schemas exposed.
+ * Useful when you want to use the schemas with asyncHandler's validation.
+ */
+export interface OpenApiBuildResult {
+    /** The OpenAPI documentation middleware */
+    middleware: any;
+    /** Request body schema if defined */
+    bodySchema?: Record<string, OpenApiSchemaProperty>;
+    /** Query parameter schemas if defined */
+    querySchema?: Record<string, OpenApiSchemaProperty>;
+    /** Whether validation was enabled on this builder */
+    validationEnabled: boolean;
+}
 /**
  * A fluent builder for constructing OpenAPI middleware.
  *
@@ -184,6 +198,12 @@ export declare class OpenApiMiddlewareBuilder {
     private options;
     /** Accumulated OpenAPI configuration from builder methods */
     private config;
+    /** Validation configuration */
+    private validationConfig;
+    /** Store the raw request body schema for validation */
+    private requestBodySchema?;
+    /** Store the raw query parameter schemas for validation */
+    private queryParamSchemas;
     /**
      * Creates a new OpenApiMiddlewareBuilder instance.
      *
@@ -365,6 +385,51 @@ export declare class OpenApiMiddlewareBuilder {
     withPathParameter(name: string, schema: OpenApiSchemaProperty, options?: {
         description?: string;
     }): this;
+    /**
+     * Enables runtime validation for this route.
+     *
+     * When enabled, the built middleware will validate incoming requests
+     * against the documented schema before the handler runs.
+     *
+     * @param options - Optional configuration for validation
+     * @param options.body - Enable body validation (default: true if request body is defined)
+     * @param options.query - Enable query parameter validation (default: true if query params are defined)
+     * @param options.enabled - Override the global validation enabled setting
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .withValidation() // Enable validation
+     *   .build();
+     * ```
+     */
+    withValidation(options?: {
+        body?: boolean;
+        query?: boolean;
+        enabled?: boolean;
+    }): this;
+    /**
+     * Builds and returns the OpenAPI middleware along with schemas.
+     *
+     * This method is useful when you want to use asyncHandler's integrated
+     * validation instead of separate validation middleware.
+     *
+     * @returns Object containing middleware and schemas
+     *
+     * @example
+     * ```typescript
+     * const {middleware, bodySchema} = createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .buildWithSchemas();
+     *
+     * router.post("/users", middleware, asyncHandler(async (req, res) => {
+     *   // handler code
+     * }, {bodySchema, validate: true}));
+     * ```
+     */
+    buildWithSchemas(): OpenApiBuildResult;
     /**
      * Builds and returns the OpenAPI middleware.
      *
@@ -372,10 +437,13 @@ export declare class OpenApiMiddlewareBuilder {
      * that integrates with the OpenAPI documentation system. If no OpenAPI
      * path is configured in options, returns a no-op middleware.
      *
+     * If validation was enabled via `withValidation()`, returns an array
+     * of middleware: [openApiDocMiddleware, validationMiddleware].
+     *
      * Default error responses (400, 401, 403, 404, 405) are automatically
      * merged with the configured responses.
      *
-     * @returns Express middleware function for OpenAPI documentation
+     * @returns Express middleware function(s) for OpenAPI documentation and optional validation
      *
      * @example
      * ```typescript