@terreno/api 0.21.0 → 0.22.0

package/dist/transformers.test.js

@@ -46,22 +46,6 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
-    }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
-    }
-    return ar;
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -81,37 +65,16 @@ var transformers_1 = require("./transformers");
     var server;
     var app;
     (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
-        var _a;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        var testData;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
                 case 0:
                     process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
-                    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];
-                    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();
+                    testData = _a.sent();
+                    admin = testData.users.admin;
+                    notAdmin = testData.users.notAdmin;
                     app = (0, tests_1.getBaseServer)();
                     (0, auth_1.setupAuth)(app, tests_1.UserModel);
                     (0, auth_1.addAuthRoutes)(app, tests_1.UserModel);
@@ -156,7 +119,7 @@ var transformers_1 = require("./transformers");
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 2:
                     foodRes = _a.sent();
-                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(2);
+                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(3);
                     return [2 /*return*/];
             }
         });
@@ -171,7 +134,7 @@ var transformers_1 = require("./transformers");
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 2:
                     foodRes = _a.sent();
-                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(3);
+                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(4);
                     return [2 /*return*/];
             }
         });
@@ -186,7 +149,7 @@ var transformers_1 = require("./transformers");
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 2:
                     foodRes = _a.sent();
-                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(3);
+                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(4);
                     spinach = foodRes.body.data.find(function (food) { return food.name === "Spinach"; });
                     (0, bun_test_1.expect)(spinach.created).toBeDefined();
                     (0, bun_test_1.expect)(spinach.id).toBeDefined();
@@ -227,7 +190,7 @@ var transformers_1 = require("./transformers");
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 2:
                     foodRes = _a.sent();
-                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(2);
+                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(3);
                     spinach = foodRes.body.data.find(function (food) { return food.name === "Spinach"; });
                     (0, bun_test_1.expect)(spinach.id).toBeDefined();
                     (0, bun_test_1.expect)(spinach.name).toBe("Spinach");
@@ -289,7 +252,7 @@ var transformers_1 = require("./transformers");
                     return [4 /*yield*/, agent.get("/food").expect(200)];
                 case 2:
                     foodRes = _a.sent();
-                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(2);
+                    (0, bun_test_1.expect)(foodRes.body.data).toHaveLength(3);
                     spinach = foodRes.body.data.find(function (food) { return food.name === "Spinach"; });
                     (0, bun_test_1.expect)(spinach.id).toBeDefined();
                     (0, bun_test_1.expect)(spinach.name).toBe("Spinach");
@@ -358,9 +321,10 @@ var transformers_1 = require("./transformers");
                 case 0: return [4 /*yield*/, server.get("/food")];
                 case 1:
                     res = _a.sent();
-                    (0, bun_test_1.expect)(res.body.data).toHaveLength(2);
+                    (0, bun_test_1.expect)(res.body.data).toHaveLength(3);
                     (0, bun_test_1.expect)(res.body.data.find(function (f) { return f.name === "Spinach"; })).toBeDefined();
                     (0, bun_test_1.expect)(res.body.data.find(function (f) { return f.name === "Carrots"; })).toBeDefined();
+                    (0, bun_test_1.expect)(res.body.data.find(function (f) { return f.name === "Pizza"; })).toBeDefined();
                     return [2 /*return*/];
             }
         });

package/package.json

@@ -46,6 +46,7 @@
   "description": "Styled after the Django & Django REST Framework, a batteries-include framework for building REST APIs with Node/Express/Mongoose.",
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
+    "@terreno/test": "workspace:*",
     "@types/bcrypt": "^6.0.0",
     "@types/bun": "^1.2.4",
     "@types/cors": "^2.8.17",
@@ -80,6 +81,16 @@
   ],
   "license": "Apache-2.0",
   "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/tests.d.ts",
+      "default": "./dist/tests.js"
+    }
+  },
   "name": "@terreno/api",
   "publishConfig": {
     "access": "public"
@@ -96,18 +107,21 @@
     "json5": "2.2.3"
   },
   "scripts": {
-    "compile": "bun tsc",
+    "compile": "node ../.github/scripts/compile-workspace-deps.js && bun tsc",
     "compile:watch": "bun tsc -w",
     "dev": "bun tsc -w",
     "docs": "typedoc --out docs src/index.ts",
     "lint": "biome check ./src",
     "lint:fix": "biome check --write ./src",
     "lint:unsafefix": "biome check --fix --unsafe ./src",
-    "test": "bun test --preload ./src/tests/bunSetup.ts --update-snapshots",
-    "test:ci": "bun test --preload ./src/tests/bunSetup.ts",
+    "test": "bun test --update-snapshots",
+    "test:ci": "bun test",
     "test:coverage": "bun run ../scripts/check-coverage.ts",
+    "test:cache:clean": "bun ./src/tests/mongoTestSetup.ts clean",
+    "test:cache:setup": "bun ./src/tests/mongoTestSetup.ts setup",
+    "test:cache:status": "bun ./src/tests/mongoTestSetup.ts status",
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.21.0"
+  "version": "0.22.0"
 }

package/src/__snapshots__/openApiBuilder.test.ts.snap

@@ -910,6 +910,7 @@ exports[`OpenApiMiddlewareBuilder snapshot tests matches OpenAPI spec snapshot 1
     "/food/stats": {
       "get": {
         "description": "Returns aggregated statistics about food items",
+        "operationId": "getFoodStats",
         "parameters": [
           {
             "description": "Filter by food category",

package/src/auth.test.ts

@@ -10,7 +10,7 @@ import {addAuthRoutes, addMeRoutes, generateTokens, setupAuth} from "./auth";
 import {Permissions} from "./permissions";
 import {getCurrentRequestContext} from "./requestContext";
 import {TerrenoApp} from "./terrenoApp";
-import {type Food, FoodModel, getBaseServer, setupDb, UserModel} from "./tests";
+import {type Food, FoodModel, getBaseServer, setupDb, setupTestData, UserModel} from "./tests";
 import {AdminOwnerTransformer} from "./transformers";
 import {timeout} from "./utils";
 
@@ -29,38 +29,16 @@ describe("auth tests", () => {
     stage: string;
     userId?: string;
   }>;
-  let notAdmin: any;
   let agent: TestAgent;
 
   beforeEach(async () => {
     // Reset to real time - don't freeze time here as passport-local-mongoose
     // lockout mechanism needs real time to progress
     setSystemTime();
-    [admin, notAdmin] = await setupDb();
+    const testData = await setupTestData();
+    admin = testData.users.admin;
     contextEvents = [];
 
-    await Promise.all([
-      FoodModel.create({
-        calories: 1,
-        created: new Date(),
-        name: "Spinach",
-        ownerId: notAdmin._id,
-      }),
-      FoodModel.create({
-        calories: 100,
-        created: Date.now() - 10,
-        hidden: true,
-        name: "Apple",
-        ownerId: admin._id,
-      }),
-      FoodModel.create({
-        calories: 100,
-        created: Date.now() - 10,
-        name: "Carrots",
-        ownerId: admin._id,
-      }),
-    ]);
-
     function addRoutes(router: express.Router): void {
       router.use(
         "/food",
@@ -217,7 +195,7 @@ describe("auth tests", () => {
     // Use token to see 2 foods + the one we just created
     const getRes = await agent.get("/food").expect(200);
 
-    expect(getRes.body.data).toHaveLength(3);
+    expect(getRes.body.data).toHaveLength(4);
     expect(getRes.body.data.find((f: any) => f.name === "Peas")).toBeDefined();
 
     const updateRes = await agent
@@ -396,7 +374,7 @@ describe("auth tests", () => {
     // Use token to see admin foods
     const getRes = await agent.get("/food").expect(200);
 
-    expect(getRes.body.data).toHaveLength(3);
+    expect(getRes.body.data).toHaveLength(4);
     const food = getRes.body.data.find((f: any) => f.name === "Apple");
     expect(food).toBeDefined();
 
@@ -826,7 +804,7 @@ describe("addAuthRoutes /refresh_token error paths", () => {
 
   beforeEach(async () => {
     setSystemTime();
-    await setupDb();
+    await setupTestData();
     app = new TerrenoApp({
       configureApp: () => {},
       skipListen: true,
@@ -891,7 +869,7 @@ describe("addMeRoutes edge cases", () => {
 
   beforeEach(async () => {
     setSystemTime();
-    await setupDb();
+    await setupTestData();
     app = new TerrenoApp({
       configureApp: () => {},
       skipListen: true,
@@ -926,4 +904,274 @@ describe("addMeRoutes edge cases", () => {
     // Either 404 (user not found in /me handler) or 401 (auth middleware rejects)
     expect([401, 404]).toContain(res.status);
   });
+
+  it("PATCH /auth/me returns 404 when user is deleted after auth", async () => {
+    const [_admin, notAdmin] = await setupDb();
+    const jwtLib = (await import("jsonwebtoken")).default;
+    const notAdminId = (notAdmin as unknown as {_id: {toString(): string}})._id;
+    const token = jwtLib.sign({id: notAdminId.toString()}, process.env.TOKEN_SECRET as string, {
+      issuer: process.env.TOKEN_ISSUER,
+    });
+    await UserModel.deleteOne({_id: notAdminId});
+    const res = await agent
+      .patch("/auth/me")
+      .set("authorization", `Bearer ${token}`)
+      .send({email: "x@x.com"});
+    expect([401, 404]).toContain(res.status);
+  });
+
+  it("PATCH /auth/me returns 403 on validation error", async () => {
+    const [admin] = await setupDb();
+    const jwtLib = (await import("jsonwebtoken")).default;
+    const adminId = (admin as unknown as {_id: {toString(): string}})._id;
+    const token = jwtLib.sign({id: adminId.toString()}, process.env.TOKEN_SECRET as string, {
+      issuer: process.env.TOKEN_ISSUER,
+    });
+    const res = await agent
+      .patch("/auth/me")
+      .set("authorization", `Bearer ${token}`)
+      .send({admin: "not_a_boolean_value_but_will_be_cast"});
+    expect([200, 403]).toContain(res.status);
+  });
+});
+
+describe("Secret prefix authorization bypass", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+
+  beforeEach(async () => {
+    setSystemTime();
+    await setupTestData();
+    app = new TerrenoApp({
+      configureApp: (router: express.Router) => {
+        router.use(
+          "/food",
+          modelRouter(FoodModel, {
+            allowAnonymous: true,
+            permissions: {
+              create: [],
+              delete: [],
+              list: [Permissions.IsAny],
+              read: [Permissions.IsAny],
+              update: [],
+            },
+          })
+        );
+      },
+      skipListen: true,
+      userModel: UserModel as any,
+    }).build();
+    agent = supertest.agent(app);
+  });
+
+  afterEach(() => {
+    setSystemTime();
+  });
+
+  it("passes through with Secret prefix authorization header without JWT decoding", async () => {
+    const res = await agent.get("/food").set("authorization", "Secret my-secret-token").expect(200);
+    expect(res.body.data).toBeDefined();
+  });
+});
+
+describe("generateTokens env integration", () => {
+  const OLD_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = {...OLD_ENV};
+    process.env.TOKEN_SECRET = "secret";
+    process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+  });
+
+  afterEach(() => {
+    process.env = OLD_ENV;
+  });
+
+  it("includes TOKEN_ISSUER in token when set", async () => {
+    process.env.TOKEN_ISSUER = "test-issuer";
+    const result = await generateTokens({_id: "user-123"});
+    const decoded = decodeTokenPayload<{iss?: string}>(result.token as string);
+    expect(decoded.iss).toBe("test-issuer");
+  });
+
+  it("generates a unique sessionId when none provided", async () => {
+    const result1 = await generateTokens({_id: "user-123"});
+    const result2 = await generateTokens({_id: "user-123"});
+    expect(result1.sessionId).toBeDefined();
+    expect(result2.sessionId).toBeDefined();
+    expect(result1.sessionId).not.toBe(result2.sessionId);
+  });
+
+  it("uses provided sessionId from options", async () => {
+    const result = await generateTokens({_id: "user-123"}, undefined, {
+      sessionId: "custom-session-id",
+    });
+    const decoded = decodeTokenPayload<{sid?: string}>(result.token as string);
+    expect(decoded.sid).toBe("custom-session-id");
+    expect(result.sessionId).toBe("custom-session-id");
+  });
+});
+
+describe("refresh_token without REFRESH_TOKEN_SECRET", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+  const OLD_ENV = process.env;
+
+  beforeEach(async () => {
+    setSystemTime();
+    process.env = {...OLD_ENV};
+    await setupTestData();
+    app = new TerrenoApp({
+      configureApp: () => {},
+      skipListen: true,
+      userModel: UserModel as any,
+    }).build();
+    agent = supertest.agent(app);
+  });
+
+  afterEach(() => {
+    setSystemTime();
+    process.env = OLD_ENV;
+  });
+
+  it("returns 401 when REFRESH_TOKEN_SECRET is not set", async () => {
+    process.env.REFRESH_TOKEN_SECRET = "";
+    const res = await agent
+      .post("/auth/refresh_token")
+      .send({refreshToken: "some-token"})
+      .expect(401);
+    expect(res.body.message).toContain("No REFRESH_TOKEN_SECRET set");
+  });
+});
+
+describe("generateTokens with custom TOKEN_EXPIRES_IN", () => {
+  const OLD_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = {...OLD_ENV};
+    process.env.TOKEN_SECRET = "secret";
+    process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+  });
+
+  afterEach(() => {
+    process.env = OLD_ENV;
+  });
+
+  it("uses TOKEN_EXPIRES_IN when set to a valid duration", async () => {
+    process.env.TOKEN_EXPIRES_IN = "1h";
+    const result = await generateTokens({_id: "user-123"});
+    expect(result.token).toBeDefined();
+    const decoded = decodeTokenPayload<{exp: number; iat: number}>(result.token as string);
+    const diffSeconds = decoded.exp - decoded.iat;
+    // 1h = 3600s
+    expect(diffSeconds).toBe(3600);
+  });
+
+  it("uses REFRESH_TOKEN_EXPIRES_IN when set to a valid duration", async () => {
+    process.env.REFRESH_TOKEN_EXPIRES_IN = "7d";
+    const result = await generateTokens({_id: "user-123"});
+    expect(result.refreshToken).toBeDefined();
+    const decoded = decodeTokenPayload<{exp: number; iat: number}>(result.refreshToken as string);
+    const diffSeconds = decoded.exp - decoded.iat;
+    // 7d = 604800s
+    expect(diffSeconds).toBe(604800);
+  });
+});
+
+describe("JWT cookie extraction and /me routes edge cases", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+  const OLD_ENV = process.env;
+
+  beforeEach(async () => {
+    setSystemTime();
+    process.env = {...OLD_ENV};
+    await setupTestData();
+    app = new TerrenoApp({
+      configureApp: () => {},
+      skipListen: true,
+      userModel: UserModel as any,
+    }).build();
+    agent = supertest.agent(app);
+  });
+
+  afterEach(() => {
+    setSystemTime();
+    process.env = OLD_ENV;
+  });
+
+  it("returns 401 for /me when no user is authenticated", async () => {
+    const res = await agent.get("/auth/me").expect(401);
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 401 for PATCH /me when no user is authenticated", async () => {
+    const res = await agent.patch("/auth/me").send({name: "Updated"}).expect(401);
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 404 for /me when user is deleted from database", async () => {
+    // Login, then delete the user, then try /me
+    const loginRes = await agent
+      .post("/auth/login")
+      .send({email: "notAdmin@example.com", password: "password"})
+      .expect(200);
+    const {token, userId} = loginRes.body.data;
+
+    // Delete the user from DB
+    await UserModel.deleteOne({_id: userId});
+
+    const freshAgent = supertest.agent(app);
+    const res = await freshAgent.get("/auth/me").set("authorization", `Bearer ${token}`);
+    // Without the user, the JWT verify succeeds but findById returns null
+    expect([401, 404]).toContain(res.status);
+  });
+});
+
+describe("login error and disabled user paths", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+
+  beforeEach(async () => {
+    setSystemTime();
+    await setupTestData();
+    app = new TerrenoApp({
+      configureApp: () => {},
+      skipListen: true,
+      userModel: UserModel as any,
+    }).build();
+    agent = supertest.agent(app);
+  });
+
+  afterEach(() => {
+    setSystemTime();
+  });
+
+  it("returns 401 with message for invalid credentials (no user found)", async () => {
+    const res = await agent
+      .post("/auth/login")
+      .send({email: "nonexistent@example.com", password: "wrong"})
+      .expect(401);
+    expect(res.body.message).toBeDefined();
+  });
+
+  it("returns 401 when disabled user tries to access protected route", async () => {
+    // Login to get token
+    const loginRes = await agent
+      .post("/auth/login")
+      .send({email: "notAdmin@example.com", password: "password"})
+      .expect(200);
+    const {token, userId} = loginRes.body.data;
+
+    // Disable the user
+    await UserModel.findByIdAndUpdate(userId, {disabled: true});
+
+    // Try to access /me with disabled user's token
+    const freshAgent = supertest.agent(app);
+    const res = await freshAgent
+      .get("/auth/me")
+      .set("authorization", `Bearer ${token}`)
+      .expect(401);
+    expect(res.body.title).toContain("disabled");
+  });
 });

package/src/models/consentForm.ts

@@ -126,7 +126,6 @@ consentFormSchema.plugin(isDeletedPlugin);
 consentFormSchema.plugin(findOneOrNone);
 consentFormSchema.plugin(findExactlyOne);
 
-export const ConsentForm = mongoose.model<ConsentFormDocument, ConsentFormModel>(
-  "ConsentForm",
-  consentFormSchema
-);
+export const ConsentForm =
+  (mongoose.models.ConsentForm as ConsentFormModel | undefined) ??
+  mongoose.model<ConsentFormDocument, ConsentFormModel>("ConsentForm", consentFormSchema);

package/src/models/consentResponse.ts

@@ -72,7 +72,9 @@ consentResponseSchema.plugin(isDeletedPlugin);
 consentResponseSchema.plugin(findOneOrNone);
 consentResponseSchema.plugin(findExactlyOne);
 
-export const ConsentResponse = mongoose.model<ConsentResponseDocument, ConsentResponseModel>(
-  "ConsentResponse",
-  consentResponseSchema
-);
+export const ConsentResponse =
+  (mongoose.models.ConsentResponse as ConsentResponseModel | undefined) ??
+  mongoose.model<ConsentResponseDocument, ConsentResponseModel>(
+    "ConsentResponse",
+    consentResponseSchema
+  );

package/src/models/versionConfig.ts

@@ -97,7 +97,6 @@ versionConfigSchema.plugin(isDeletedPlugin);
 versionConfigSchema.plugin(findOneOrNone);
 versionConfigSchema.plugin(findExactlyOne);
 
-export const VersionConfig = mongoose.model<VersionConfigDocument, VersionConfigModel>(
-  "VersionConfig",
-  versionConfigSchema
-);
+export const VersionConfig =
+  (mongoose.models.VersionConfig as VersionConfigModel | undefined) ??
+  mongoose.model<VersionConfigDocument, VersionConfigModel>("VersionConfig", versionConfigSchema);

package/src/openApiBuilder.test.ts

@@ -16,6 +16,7 @@ function addRoutesWithBuilder(router: Router, options?: Partial<ModelRouterOptio
   const statsMiddleware = createOpenApiBuilder(options ?? {})
     .withTags(["Stats"])
     .withSummary("Get food statistics")
+    .withOperationId("getFoodStats")
     .withDescription("Returns aggregated statistics about food items")
     .withQueryParameter(
       "category",
@@ -195,6 +196,14 @@ describe("OpenApiMiddlewareBuilder", () => {
       expect(categoryParam.required).toBe(false);
     });
 
+    it("includes the explicit operationId in OpenAPI spec", async () => {
+      server = supertest(app);
+      const res = await server.get("/openapi.json").expect(200);
+
+      const statsPath = res.body.paths["/food/stats"];
+      expect(statsPath.get.operationId).toBe("getFoodStats");
+    });
+
     it("includes request body schema in OpenAPI spec", async () => {
       server = supertest(app);
       const res = await server.get("/openapi.json").expect(200);

package/src/openApiBuilder.ts

@@ -213,6 +213,8 @@ interface OpenApiConfig {
   summary?: string;
   /** Detailed description of the operation */
   description?: string;
+  /** Explicit operationId for the operation */
+  operationId?: string;
   /** Operation parameters (query, path, header) */
   parameters?: OpenApiParameter[];
   /** Request body configuration */
@@ -359,6 +361,28 @@ export class OpenApiMiddlewareBuilder {
     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");
+   * ```
+   */
+  withOperationId(operationId: string): this {
+    this.config.operationId = operationId;
+    return this;
+  }
+
   /**
    * Sets the description for the OpenAPI operation.
    *