@terreno/api 0.21.0 → 0.22.0

package/bunfig.toml

@@ -1,5 +1,5 @@
 [test]
-preload = ["./src/tests/bunSetup.ts"]
+preload = ["./src/tests/testEnv.ts", "./src/tests/bunSetup.ts"]
 root = "./src"
 coverage = true
 coveragePathIgnorePatterns = ["dist/**", "**/*.test.ts", "**/tests/**", "**/vendor/**", "../**"]

package/dist/auth.test.js

@@ -118,7 +118,6 @@ var decodeTokenPayload = function (token) {
     var app;
     var admin;
     var contextEvents;
-    var notAdmin;
     var agent;
     (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
         function addRoutes(router) {
@@ -202,40 +201,18 @@ var decodeTokenPayload = function (token) {
                 }); },
             }));
         }
-        var _a;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        var testData;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
                 case 0:
                     // Reset to real time - don't freeze time here as passport-local-mongoose
                     // lockout mechanism needs real time to progress
                     (0, bun_test_1.setSystemTime)();
-                    return [4 /*yield*/, (0, tests_1.setupDb)()];
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
                 case 1:
-                    _a = __read.apply(void 0, [_b.sent(), 2]), admin = _a[0], notAdmin = _a[1];
+                    testData = _a.sent();
+                    admin = testData.users.admin;
                     contextEvents = [];
-                    return [4 /*yield*/, Promise.all([
-                            tests_1.FoodModel.create({
-                                calories: 1,
-                                created: new Date(),
-                                name: "Spinach",
-                                ownerId: notAdmin._id,
-                            }),
-                            tests_1.FoodModel.create({
-                                calories: 100,
-                                created: Date.now() - 10,
-                                hidden: true,
-                                name: "Apple",
-                                ownerId: admin._id,
-                            }),
-                            tests_1.FoodModel.create({
-                                calories: 100,
-                                created: Date.now() - 10,
-                                name: "Carrots",
-                                ownerId: admin._id,
-                            }),
-                        ])];
-                case 2:
-                    _b.sent();
                     app = new terrenoApp_1.TerrenoApp({
                         configureApp: addRoutes,
                         skipListen: true,
@@ -315,7 +292,7 @@ var decodeTokenPayload = function (token) {
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 7:
                     getRes = _b.sent();
-                    (0, bun_test_1.expect)(getRes.body.data).toHaveLength(3);
+                    (0, bun_test_1.expect)(getRes.body.data).toHaveLength(4);
                     (0, bun_test_1.expect)(getRes.body.data.find(function (f) { return f.name === "Peas"; })).toBeDefined();
                     return [4 /*yield*/, agent
                             .patch("/food/".concat(food._id))
@@ -547,7 +524,7 @@ var decodeTokenPayload = function (token) {
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 5:
                     getRes = _b.sent();
-                    (0, bun_test_1.expect)(getRes.body.data).toHaveLength(3);
+                    (0, bun_test_1.expect)(getRes.body.data).toHaveLength(4);
                     food = getRes.body.data.find(function (f) { return f.name === "Apple"; });
                     (0, bun_test_1.expect)(food).toBeDefined();
                     return [4 /*yield*/, agent
@@ -1155,7 +1132,7 @@ var decodeTokenPayload = function (token) {
             switch (_a.label) {
                 case 0:
                     (0, bun_test_1.setSystemTime)();
-                    return [4 /*yield*/, (0, tests_1.setupDb)()];
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
                 case 1:
                     _a.sent();
                     app = new terrenoApp_1.TerrenoApp({
@@ -1265,7 +1242,7 @@ var decodeTokenPayload = function (token) {
             switch (_a.label) {
                 case 0:
                     (0, bun_test_1.setSystemTime)();
-                    return [4 /*yield*/, (0, tests_1.setupDb)()];
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
                 case 1:
                     _a.sent();
                     app = new terrenoApp_1.TerrenoApp({
@@ -1326,4 +1303,402 @@ var decodeTokenPayload = function (token) {
             }
         });
     }); });
+    (0, bun_test_1.it)("PATCH /auth/me returns 404 when user is deleted after auth", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, _admin, notAdmin, jwtLib, notAdminId, token, res;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 1:
+                    _a = __read.apply(void 0, [_b.sent(), 2]), _admin = _a[0], notAdmin = _a[1];
+                    return [4 /*yield*/, Promise.resolve().then(function () { return __importStar(require("jsonwebtoken")); })];
+                case 2:
+                    jwtLib = (_b.sent()).default;
+                    notAdminId = notAdmin._id;
+                    token = jwtLib.sign({ id: notAdminId.toString() }, process.env.TOKEN_SECRET, {
+                        issuer: process.env.TOKEN_ISSUER,
+                    });
+                    return [4 /*yield*/, tests_1.UserModel.deleteOne({ _id: notAdminId })];
+                case 3:
+                    _b.sent();
+                    return [4 /*yield*/, agent
+                            .patch("/auth/me")
+                            .set("authorization", "Bearer ".concat(token))
+                            .send({ email: "x@x.com" })];
+                case 4:
+                    res = _b.sent();
+                    (0, bun_test_1.expect)([401, 404]).toContain(res.status);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("PATCH /auth/me returns 403 on validation error", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, admin, jwtLib, adminId, token, res;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 1:
+                    _a = __read.apply(void 0, [_b.sent(), 1]), admin = _a[0];
+                    return [4 /*yield*/, Promise.resolve().then(function () { return __importStar(require("jsonwebtoken")); })];
+                case 2:
+                    jwtLib = (_b.sent()).default;
+                    adminId = admin._id;
+                    token = jwtLib.sign({ id: adminId.toString() }, process.env.TOKEN_SECRET, {
+                        issuer: process.env.TOKEN_ISSUER,
+                    });
+                    return [4 /*yield*/, agent
+                            .patch("/auth/me")
+                            .set("authorization", "Bearer ".concat(token))
+                            .send({ admin: "not_a_boolean_value_but_will_be_cast" })];
+                case 3:
+                    res = _b.sent();
+                    (0, bun_test_1.expect)([200, 403]).toContain(res.status);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("Secret prefix authorization bypass", function () {
+    var app;
+    var agent;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, bun_test_1.setSystemTime)();
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
+                case 1:
+                    _a.sent();
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: function (router) {
+                            router.use("/food", (0, api_1.modelRouter)(tests_1.FoodModel, {
+                                allowAnonymous: true,
+                                permissions: {
+                                    create: [],
+                                    delete: [],
+                                    list: [permissions_1.Permissions.IsAny],
+                                    read: [permissions_1.Permissions.IsAny],
+                                    update: [],
+                                },
+                            }));
+                        },
+                        skipListen: true,
+                        userModel: tests_1.UserModel,
+                    }).build();
+                    agent = supertest_1.default.agent(app);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () {
+        (0, bun_test_1.setSystemTime)();
+    });
+    (0, bun_test_1.it)("passes through with Secret prefix authorization header without JWT decoding", 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("/food").set("authorization", "Secret my-secret-token").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.data).toBeDefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("generateTokens env integration", function () {
+    var OLD_ENV = process.env;
+    (0, bun_test_1.beforeEach)(function () {
+        process.env = __assign({}, OLD_ENV);
+        process.env.TOKEN_SECRET = "secret";
+        process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+    });
+    (0, bun_test_1.afterEach)(function () {
+        process.env = OLD_ENV;
+    });
+    (0, bun_test_1.it)("includes TOKEN_ISSUER in token when set", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var result, decoded;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    process.env.TOKEN_ISSUER = "test-issuer";
+                    return [4 /*yield*/, (0, auth_1.generateTokens)({ _id: "user-123" })];
+                case 1:
+                    result = _a.sent();
+                    decoded = decodeTokenPayload(result.token);
+                    (0, bun_test_1.expect)(decoded.iss).toBe("test-issuer");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("generates a unique sessionId when none provided", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var result1, result2;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, (0, auth_1.generateTokens)({ _id: "user-123" })];
+                case 1:
+                    result1 = _a.sent();
+                    return [4 /*yield*/, (0, auth_1.generateTokens)({ _id: "user-123" })];
+                case 2:
+                    result2 = _a.sent();
+                    (0, bun_test_1.expect)(result1.sessionId).toBeDefined();
+                    (0, bun_test_1.expect)(result2.sessionId).toBeDefined();
+                    (0, bun_test_1.expect)(result1.sessionId).not.toBe(result2.sessionId);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("uses provided sessionId from options", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var result, decoded;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, (0, auth_1.generateTokens)({ _id: "user-123" }, undefined, {
+                        sessionId: "custom-session-id",
+                    })];
+                case 1:
+                    result = _a.sent();
+                    decoded = decodeTokenPayload(result.token);
+                    (0, bun_test_1.expect)(decoded.sid).toBe("custom-session-id");
+                    (0, bun_test_1.expect)(result.sessionId).toBe("custom-session-id");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("refresh_token without REFRESH_TOKEN_SECRET", function () {
+    var app;
+    var agent;
+    var OLD_ENV = process.env;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, bun_test_1.setSystemTime)();
+                    process.env = __assign({}, OLD_ENV);
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
+                case 1:
+                    _a.sent();
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: function () { },
+                        skipListen: true,
+                        userModel: tests_1.UserModel,
+                    }).build();
+                    agent = supertest_1.default.agent(app);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () {
+        (0, bun_test_1.setSystemTime)();
+        process.env = OLD_ENV;
+    });
+    (0, bun_test_1.it)("returns 401 when REFRESH_TOKEN_SECRET is not set", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    process.env.REFRESH_TOKEN_SECRET = "";
+                    return [4 /*yield*/, agent
+                            .post("/auth/refresh_token")
+                            .send({ refreshToken: "some-token" })
+                            .expect(401)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.message).toContain("No REFRESH_TOKEN_SECRET set");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("generateTokens with custom TOKEN_EXPIRES_IN", function () {
+    var OLD_ENV = process.env;
+    (0, bun_test_1.beforeEach)(function () {
+        process.env = __assign({}, OLD_ENV);
+        process.env.TOKEN_SECRET = "secret";
+        process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+    });
+    (0, bun_test_1.afterEach)(function () {
+        process.env = OLD_ENV;
+    });
+    (0, bun_test_1.it)("uses TOKEN_EXPIRES_IN when set to a valid duration", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var result, decoded, diffSeconds;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    process.env.TOKEN_EXPIRES_IN = "1h";
+                    return [4 /*yield*/, (0, auth_1.generateTokens)({ _id: "user-123" })];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result.token).toBeDefined();
+                    decoded = decodeTokenPayload(result.token);
+                    diffSeconds = decoded.exp - decoded.iat;
+                    // 1h = 3600s
+                    (0, bun_test_1.expect)(diffSeconds).toBe(3600);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("uses REFRESH_TOKEN_EXPIRES_IN when set to a valid duration", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var result, decoded, diffSeconds;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    process.env.REFRESH_TOKEN_EXPIRES_IN = "7d";
+                    return [4 /*yield*/, (0, auth_1.generateTokens)({ _id: "user-123" })];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result.refreshToken).toBeDefined();
+                    decoded = decodeTokenPayload(result.refreshToken);
+                    diffSeconds = decoded.exp - decoded.iat;
+                    // 7d = 604800s
+                    (0, bun_test_1.expect)(diffSeconds).toBe(604800);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("JWT cookie extraction and /me routes edge cases", function () {
+    var app;
+    var agent;
+    var OLD_ENV = process.env;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, bun_test_1.setSystemTime)();
+                    process.env = __assign({}, OLD_ENV);
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
+                case 1:
+                    _a.sent();
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: function () { },
+                        skipListen: true,
+                        userModel: tests_1.UserModel,
+                    }).build();
+                    agent = supertest_1.default.agent(app);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () {
+        (0, bun_test_1.setSystemTime)();
+        process.env = OLD_ENV;
+    });
+    (0, bun_test_1.it)("returns 401 for /me when no user is authenticated", 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/me").expect(401)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.status).toBe(401);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns 401 for PATCH /me when no user is authenticated", 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.patch("/auth/me").send({ name: "Updated" }).expect(401)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.status).toBe(401);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns 404 for /me when user is deleted from database", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var loginRes, _a, token, userId, freshAgent, res;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, agent
+                        .post("/auth/login")
+                        .send({ email: "notAdmin@example.com", password: "password" })
+                        .expect(200)];
+                case 1:
+                    loginRes = _b.sent();
+                    _a = loginRes.body.data, token = _a.token, userId = _a.userId;
+                    // Delete the user from DB
+                    return [4 /*yield*/, tests_1.UserModel.deleteOne({ _id: userId })];
+                case 2:
+                    // Delete the user from DB
+                    _b.sent();
+                    freshAgent = supertest_1.default.agent(app);
+                    return [4 /*yield*/, freshAgent.get("/auth/me").set("authorization", "Bearer ".concat(token))];
+                case 3:
+                    res = _b.sent();
+                    // Without the user, the JWT verify succeeds but findById returns null
+                    (0, bun_test_1.expect)([401, 404]).toContain(res.status);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("login error and disabled user paths", function () {
+    var app;
+    var agent;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, bun_test_1.setSystemTime)();
+                    return [4 /*yield*/, (0, tests_1.setupTestData)()];
+                case 1:
+                    _a.sent();
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: function () { },
+                        skipListen: true,
+                        userModel: tests_1.UserModel,
+                    }).build();
+                    agent = supertest_1.default.agent(app);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () {
+        (0, bun_test_1.setSystemTime)();
+    });
+    (0, bun_test_1.it)("returns 401 with message for invalid credentials (no user found)", 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
+                        .post("/auth/login")
+                        .send({ email: "nonexistent@example.com", password: "wrong" })
+                        .expect(401)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.message).toBeDefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns 401 when disabled user tries to access protected route", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var loginRes, _a, token, userId, freshAgent, res;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, agent
+                        .post("/auth/login")
+                        .send({ email: "notAdmin@example.com", password: "password" })
+                        .expect(200)];
+                case 1:
+                    loginRes = _b.sent();
+                    _a = loginRes.body.data, token = _a.token, userId = _a.userId;
+                    // Disable the user
+                    return [4 /*yield*/, tests_1.UserModel.findByIdAndUpdate(userId, { disabled: true })];
+                case 2:
+                    // Disable the user
+                    _b.sent();
+                    freshAgent = supertest_1.default.agent(app);
+                    return [4 /*yield*/, freshAgent
+                            .get("/auth/me")
+                            .set("authorization", "Bearer ".concat(token))
+                            .expect(401)];
+                case 3:
+                    res = _b.sent();
+                    (0, bun_test_1.expect)(res.body.title).toContain("disabled");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
 });

package/dist/models/consentForm.js

@@ -2,6 +2,7 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConsentForm = void 0;
 var mongoose_1 = __importDefault(require("mongoose"));
@@ -120,4 +121,4 @@ consentFormSchema.plugin(plugins_1.createdUpdatedPlugin);
 consentFormSchema.plugin(plugins_1.isDeletedPlugin);
 consentFormSchema.plugin(plugins_1.findOneOrNone);
 consentFormSchema.plugin(plugins_1.findExactlyOne);
-exports.ConsentForm = mongoose_1.default.model("ConsentForm", consentFormSchema);
+exports.ConsentForm = (_a = mongoose_1.default.models.ConsentForm) !== null && _a !== void 0 ? _a : mongoose_1.default.model("ConsentForm", consentFormSchema);

package/dist/models/consentResponse.js

@@ -2,6 +2,7 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConsentResponse = void 0;
 var mongoose_1 = __importDefault(require("mongoose"));
@@ -70,4 +71,4 @@ consentResponseSchema.plugin(plugins_1.createdUpdatedPlugin);
 consentResponseSchema.plugin(plugins_1.isDeletedPlugin);
 consentResponseSchema.plugin(plugins_1.findOneOrNone);
 consentResponseSchema.plugin(plugins_1.findExactlyOne);
-exports.ConsentResponse = mongoose_1.default.model("ConsentResponse", consentResponseSchema);
+exports.ConsentResponse = (_a = mongoose_1.default.models.ConsentResponse) !== null && _a !== void 0 ? _a : mongoose_1.default.model("ConsentResponse", consentResponseSchema);

package/dist/models/versionConfig.js

@@ -2,6 +2,7 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersionConfig = void 0;
 var mongoose_1 = __importDefault(require("mongoose"));
@@ -71,4 +72,4 @@ versionConfigSchema.plugin(plugins_1.createdUpdatedPlugin);
 versionConfigSchema.plugin(plugins_1.isDeletedPlugin);
 versionConfigSchema.plugin(plugins_1.findOneOrNone);
 versionConfigSchema.plugin(plugins_1.findExactlyOne);
-exports.VersionConfig = mongoose_1.default.model("VersionConfig", versionConfigSchema);
+exports.VersionConfig = (_a = mongoose_1.default.models.VersionConfig) !== null && _a !== void 0 ? _a : mongoose_1.default.model("VersionConfig", versionConfigSchema);

package/dist/openApiBuilder.d.ts

@@ -272,6 +272,24 @@ export declare class OpenApiMiddlewareBuilder {
      * ```
      */
     withSummary(summary: string): this;
+    /**
+     * Sets an explicit `operationId` for the OpenAPI operation.
+     *
+     * The `operationId` is a unique string used to identify an operation. Client and SDK
+     * generators (e.g. RTK Query codegen) derive generated function and hook names from it,
+     * so setting it keeps generated names stable and readable for routes whose URL path would
+     * otherwise produce unwieldy names (e.g. deeply nested routes). It must be unique across
+     * the whole OpenAPI document.
+     *
+     * @param operationId - Unique operation identifier (e.g. "getUserStats")
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withOperationId("getUserStats");
+     * ```
+     */
+    withOperationId(operationId: string): this;
     /**
      * Sets the description for the OpenAPI operation.
      *

package/dist/openApiBuilder.js

@@ -121,6 +121,27 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
         this.config.summary = summary;
         return this;
     };
+    /**
+     * Sets an explicit `operationId` for the OpenAPI operation.
+     *
+     * The `operationId` is a unique string used to identify an operation. Client and SDK
+     * generators (e.g. RTK Query codegen) derive generated function and hook names from it,
+     * so setting it keeps generated names stable and readable for routes whose URL path would
+     * otherwise produce unwieldy names (e.g. deeply nested routes). It must be unique across
+     * the whole OpenAPI document.
+     *
+     * @param operationId - Unique operation identifier (e.g. "getUserStats")
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withOperationId("getUserStats");
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withOperationId = function (operationId) {
+        this.config.operationId = operationId;
+        return this;
+    };
     /**
      * Sets the description for the OpenAPI operation.
      *

package/dist/openApiBuilder.test.js

@@ -64,6 +64,7 @@ function addRoutesWithBuilder(router, options) {
     var statsMiddleware = (0, openApiBuilder_1.createOpenApiBuilder)(options !== null && options !== void 0 ? options : {})
         .withTags(["Stats"])
         .withSummary("Get food statistics")
+        .withOperationId("getFoodStats")
         .withDescription("Returns aggregated statistics about food items")
         .withQueryParameter("category", { type: "string" }, {
         description: "Filter by food category",
@@ -220,6 +221,21 @@ function addRoutesWithBuilder(router, options) {
                 }
             });
         }); });
+        (0, bun_test_1.it)("includes the explicit operationId in OpenAPI spec", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res, statsPath;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        server = (0, supertest_1.default)(app);
+                        return [4 /*yield*/, server.get("/openapi.json").expect(200)];
+                    case 1:
+                        res = _a.sent();
+                        statsPath = res.body.paths["/food/stats"];
+                        (0, bun_test_1.expect)(statsPath.get.operationId).toBe("getFoodStats");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
         (0, bun_test_1.it)("includes request body schema in OpenAPI spec", function () { return __awaiter(void 0, void 0, void 0, function () {
             var res, reportsPath, requestBody, schema;
             return __generator(this, function (_a) {