@terreno/api 0.20.2 → 0.22.0

package/src/middleware.ts

@@ -1,6 +1,8 @@
 import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
 
+import {getCurrentRequestContext} from "./requestContext";
+
 /**
  * Express middleware that captures the app version from the request header
  * and adds it as a tag to the current Sentry scope.
@@ -20,3 +22,58 @@ export const sentryAppVersionMiddleware = (
   }
   next();
 };
+
+/**
+ * OpenAPI vendor routes that must return pristine JSON (no injected requestId).
+ * Matches @wesleytodd/openapi: main spec, per-component JSON, and validate payload.
+ */
+const isOpenApiToolingJsonRequest = (req: Request): boolean => {
+  if (req.method !== "GET") {
+    return false;
+  }
+  const {path} = req;
+  if (path === "/openapi.json") {
+    return true;
+  }
+  if (path === "/openapi/validate") {
+    return true;
+  }
+  if (path.startsWith("/openapi/components/") && path.endsWith(".json")) {
+    return true;
+  }
+  return false;
+};
+
+/**
+ * TerrenoApp middleware: augments `res.json` so plain-object payloads include
+ * `requestId` for client correlation. Skips OpenAPI tooling GET JSON routes
+ * (`/openapi.json`, `/openapi/components/...json`, `/openapi/validate`) so
+ * machine-consumed payloads stay valid. Does not wrap arrays or primitives.
+ */
+export const jsonResponseRequestIdMiddleware = (
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void => {
+  const originalJson = res.json.bind(res);
+  res.json = (body?: unknown): Response => {
+    if (isOpenApiToolingJsonRequest(req)) {
+      return originalJson(body);
+    }
+
+    const requestId =
+      (req as Request & {requestId?: string}).requestId ?? getCurrentRequestContext()?.requestId;
+
+    if (!requestId) {
+      return originalJson(body);
+    }
+
+    if (body !== null && body !== undefined && typeof body === "object" && !Array.isArray(body)) {
+      return originalJson({...(body as Record<string, unknown>), requestId});
+    }
+
+    return originalJson(body);
+  };
+
+  next();
+};

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/openApi.test.ts

@@ -6,8 +6,6 @@ import supertest from "supertest";
 import type TestAgent from "supertest/lib/agent";
 
 import {type ModelRouterOptions, modelRouter} from "./api";
-import {addAuthRoutes, setupAuth} from "./auth";
-import {setupServer} from "./expressServer";
 import {
   createOpenApiMiddleware,
   deleteOpenApiMiddleware,
@@ -17,6 +15,7 @@ import {
   readOpenApiMiddleware,
 } from "./openApi";
 import {Permissions} from "./permissions";
+import {TerrenoApp} from "./terrenoApp";
 import {FoodModel, setupDb, UserModel} from "./tests";
 
 function getMessageSummaryOpenApiMiddleware(options: Partial<ModelRouterOptions<any>>): any {
@@ -90,13 +89,11 @@ describe("openApi", () => {
     process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
     process.env.ENABLE_SWAGGER = "true";
 
-    app = setupServer({
-      addRoutes,
+    app = new TerrenoApp({
+      configureApp: addRoutes,
       skipListen: true,
       userModel: UserModel as any,
-    });
-    setupAuth(app, UserModel as any);
-    addAuthRoutes(app, UserModel as any);
+    }).build();
   });
 
   it("gets the openapi.json", async () => {
@@ -246,13 +243,11 @@ describe("openApi without swagger", () => {
     process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
     process.env.ENABLE_SWAGGER = "false";
 
-    app = setupServer({
-      addRoutes,
+    app = new TerrenoApp({
+      configureApp: addRoutes,
       skipListen: true,
       userModel: UserModel as any,
-    });
-    setupAuth(app, UserModel as any);
-    addAuthRoutes(app, UserModel as any);
+    }).build();
   });
 
   it("does not have the swagger ui", async () => {
@@ -268,13 +263,11 @@ describe("openApi populate", () => {
   beforeEach(async () => {
     process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
 
-    app = setupServer({
-      addRoutes: addRoutesPopulate,
+    app = new TerrenoApp({
+      configureApp: addRoutesPopulate,
       skipListen: true,
       userModel: UserModel as any,
-    });
-    setupAuth(app, UserModel as any);
-    addAuthRoutes(app, UserModel as any);
+    }).build();
   });
 
   it("gets the openapi.json with populate", async () => {

package/src/openApiBuilder.test.ts

@@ -6,10 +6,9 @@ import supertest from "supertest";
 import type TestAgent from "supertest/lib/agent";
 
 import {type ModelRouterOptions, modelRouter} from "./api";
-import {addAuthRoutes, setupAuth} from "./auth";
-import {setupServer} from "./expressServer";
 import {createOpenApiBuilder, OpenApiMiddlewareBuilder} from "./openApiBuilder";
 import {Permissions} from "./permissions";
+import {TerrenoApp} from "./terrenoApp";
 import {FoodModel, UserModel} from "./tests";
 
 function addRoutesWithBuilder(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
@@ -17,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",
@@ -145,13 +145,11 @@ describe("OpenApiMiddlewareBuilder", () => {
     process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
     process.env.ENABLE_SWAGGER = "true";
 
-    app = setupServer({
-      addRoutes: addRoutesWithBuilder,
+    app = new TerrenoApp({
+      configureApp: addRoutesWithBuilder,
       skipListen: true,
       userModel: UserModel as any,
-    });
-    setupAuth(app, UserModel as any);
-    addAuthRoutes(app, UserModel as any);
+    }).build();
   });
 
   describe("builder pattern", () => {
@@ -198,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);
@@ -302,7 +308,11 @@ describe("OpenApiMiddlewareBuilder", () => {
     it("stats endpoint returns correct data", async () => {
       server = supertest(app);
       const res = await server.get("/food/stats").expect(200);
-      expect(res.body).toEqual({avgCalories: 250, count: 10});
+      expect(res.body).toEqual({
+        avgCalories: 250,
+        count: 10,
+        requestId: res.headers["x-request-id"],
+      });
     });
 
     it("reports endpoint returns correct data", async () => {
@@ -311,7 +321,10 @@ describe("OpenApiMiddlewareBuilder", () => {
         .post("/food/reports")
         .send({endDate: "2024-12-31", startDate: "2024-01-01"})
         .expect(201);
-      expect(res.body).toEqual({reportId: "report-123"});
+      expect(res.body).toEqual({
+        reportId: "report-123",
+        requestId: res.headers["x-request-id"],
+      });
     });
 
     it("categories endpoint returns array data", async () => {
@@ -325,7 +338,11 @@ describe("OpenApiMiddlewareBuilder", () => {
     it("category by id endpoint returns correct data", async () => {
       server = supertest(app);
       const res = await server.get("/food/categories/cat-123").expect(200);
-      expect(res.body).toEqual({id: "cat-123", name: "Fruits"});
+      expect(res.body).toEqual({
+        id: "cat-123",
+        name: "Fruits",
+        requestId: res.headers["x-request-id"],
+      });
     });
   });
 

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.
    *

package/src/permissions.test.ts

@@ -13,7 +13,7 @@ import {
   FoodModel,
   getBaseServer,
   RequiredModel,
-  setupDb,
+  setupTestData,
   UserModel,
 } from "./tests";
 
@@ -24,22 +24,7 @@ describe("permissions", () => {
   beforeEach(async () => {
     process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
 
-    const [admin, notAdmin] = await setupDb();
-
-    await Promise.all([
-      FoodModel.create({
-        calories: 1,
-        created: new Date(),
-        name: "Spinach",
-        ownerId: notAdmin._id,
-      }),
-      FoodModel.create({
-        calories: 100,
-        created: Date.now() - 10,
-        name: "Apple",
-        ownerId: admin._id,
-      }),
-    ]);
+    await setupTestData();
     app = getBaseServer();
     setupAuth(app, UserModel as any);
     addAuthRoutes(app, UserModel as any);
@@ -74,12 +59,12 @@ describe("permissions", () => {
   describe("anonymous food", () => {
     it("list", async () => {
       const res = await server.get("/food").expect(200);
-      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data).toHaveLength(4);
     });
 
     it("get", async () => {
       const res = await server.get("/food").expect(200);
-      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data).toHaveLength(4);
       const res2 = await server.get(`/food/${res.body.data[0]._id}`).expect(200);
       expect(res.body.data[0]._id).toBe(res2.body.data._id);
     });
@@ -116,12 +101,12 @@ describe("permissions", () => {
 
     it("list", async () => {
       const res = await agent.get("/food").expect(200);
-      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data).toHaveLength(4);
     });
 
     it("get", async () => {
       const res = await agent.get("/food").expect(200);
-      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data).toHaveLength(4);
       const res2 = await server.get(`/food/${res.body.data[0]._id}`).expect(200);
       expect(res.body.data[0]._id).toBe(res2.body.data._id);
     });
@@ -175,12 +160,12 @@ describe("permissions", () => {
 
     it("list", async () => {
       const res = await agent.get("/food");
-      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data).toHaveLength(4);
     });
 
     it("get", async () => {
       const res = await agent.get("/food");
-      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data).toHaveLength(4);
       const res2 = await agent.get(`/food/${res.body.data[0]._id}`);
       expect(res.body.data[0]._id).toBe(res2.body.data._id);
     });

package/src/populate.test.ts

@@ -3,7 +3,7 @@ import {beforeEach, describe, expect, it} from "bun:test";
 import mongoose, {type Document, type HydratedDocument, Schema} from "mongoose";
 
 import {fixMixedFields, getOpenApiSpecForModel, unpopulate} from "./populate";
-import {FoodModel, setupDb, type User, UserModel} from "./tests";
+import {FoodModel, setupTestData, type User, UserModel} from "./tests";
 
 describe("populate functions", () => {
   let admin: HydratedDocument<User>;
@@ -13,32 +13,17 @@ describe("populate functions", () => {
   let spinach: any;
 
   beforeEach(async () => {
-    [admin, notAdmin] = await setupDb();
-
-    [spinach] = await Promise.all([
-      FoodModel.create({
-        calories: 1,
-        created: new Date("2021-12-03T00:00:20.000Z"),
-        eatenBy: [admin._id],
-        hidden: false,
-        likesIds: [
-          {likes: true, userId: admin._id},
-          {likes: false, userId: notAdmin._id},
-        ],
-        name: "Spinach",
-        ownerId: admin._id,
-        source: {
-          name: "Brand",
-        },
-      }),
-    ]);
+    const testData = await setupTestData();
+    admin = testData.users.admin;
+    notAdmin = testData.users.notAdmin;
+    spinach = testData.foods.spinach;
   });
 
   it("unpopulate", async () => {
     let populated = await spinach.populate("ownerId");
     populated = await populated.populate("eatenBy");
     populated = await populated.populate("likesIds.userId");
-    expect(populated.ownerId.name).toBe("Admin");
+    expect(populated.ownerId.name).toBe("Not Admin");
     expect(populated.eatenBy[0].id).toBe(admin.id);
     expect(populated.eatenBy[0].name).toBe("Admin");
     expect(populated.likesIds[0].userId.id).toBe(admin.id);
@@ -49,7 +34,7 @@ describe("populate functions", () => {
     // noExplicitAny: unpopulate returns Document<T> which doesn't expose model properties; would require refactoring the return type
     let unpopulated: any = unpopulate(populated, "ownerId");
     expect(spinach.ownerId.name).toBeUndefined();
-    expect(unpopulated.ownerId.toString()).toBe(admin.id);
+    expect(unpopulated.ownerId.toString()).toBe(notAdmin.id);
     // Ensure nothing else was touched.
     expect(populated.likesIds[0].userId.id).toBe(admin.id);
     expect(populated.likesIds[0].userId.name).toBe("Admin");

package/src/realtime/changeStreamWatcher.ts

@@ -1,4 +1,3 @@
-// biome-ignore-all lint/suspicious/noExplicitAny: change stream and socket handlers use dynamic document shapes
 import * as Sentry from "@sentry/bun";
 import type express from "express";
 import {DateTime} from "luxon";
@@ -98,7 +97,7 @@ const getSocketsInRoom = (io: Server, room: string): RealtimeSocketWithAuth[] =>
 const canReadDocument = async (
   entry: RealtimeRegistryEntry,
   user?: User,
-  doc?: any
+  doc?: Record<string, unknown>
 ): Promise<boolean> => {
   return checkPermissions("read", entry.options.permissions.read, user, doc);
 };
@@ -107,7 +106,11 @@ const canReadDocument = async (
  * Determine which Socket.io rooms to emit to based on the room strategy.
  * Exported for testing.
  */
-export const resolveRooms = (entry: RealtimeRegistryEntry, doc: any, method: string): string[] => {
+export const resolveRooms = (
+  entry: RealtimeRegistryEntry,
+  doc: Record<string, unknown>,
+  method: string
+): string[] => {
   const {roomStrategy} = entry.config;
   // Use the collection tag (e.g. "todos") for model rooms, matching what the frontend subscribes to
   const collectionTag = getCollectionTag(entry.routePath);
@@ -120,7 +123,7 @@ export const resolveRooms = (entry: RealtimeRegistryEntry, doc: any, method: str
 
   switch (roomStrategy) {
     case "owner": {
-      const ownerId = doc?.ownerId?.toString?.() ?? doc?.ownerId;
+      const ownerId = doc?.ownerId != null ? String(doc.ownerId) : undefined;
       if (ownerId) {
         return [`user:${ownerId}`];
       }
@@ -169,10 +172,10 @@ export const ensureApiId = (data: unknown): unknown => {
  */
 export const serializeDoc = async (
   entry: RealtimeRegistryEntry,
-  doc: any,
+  doc: Record<string, unknown>,
   method: "create" | "update" | "delete",
   user?: User
-): Promise<any> => {
+): Promise<unknown> => {
   if (entry.config.realtimeResponseHandler) {
     try {
       return ensureApiId(await entry.config.realtimeResponseHandler(doc, method));
@@ -203,7 +206,9 @@ export const serializeDoc = async (
     }
   }
 
-  return ensureApiId(typeof doc.toJSON === "function" ? doc.toJSON() : doc);
+  return ensureApiId(
+    typeof doc.toJSON === "function" ? (doc as {toJSON: () => unknown}).toJSON() : doc
+  );
 };
 
 export const emitToAuthorizedRoom = async (
@@ -211,7 +216,7 @@ export const emitToAuthorizedRoom = async (
   room: string,
   event: RealtimeEvent,
   entry: RealtimeRegistryEntry,
-  fullDocument: any,
+  fullDocument: Record<string, unknown> | undefined,
   logDebug: (msg: string) => void
 ): Promise<void> => {
   const sockets = getSocketsInRoom(io, room);
@@ -263,7 +268,7 @@ export const emitToDocumentAndQueryRooms = async (
   io: Server,
   collection: string,
   event: RealtimeEvent,
-  fullDocument: any,
+  fullDocument: Record<string, unknown> | undefined,
   logDebug: (msg: string) => void,
   entry?: RealtimeRegistryEntry
 ): Promise<void> => {
@@ -495,7 +500,7 @@ export const startChangeStreamWatcher = (
             rooms = [`model:${collectionTag}`];
           }
         } else {
-          rooms = resolveRooms(entry, fullDocument, method);
+          rooms = resolveRooms(entry, fullDocument ?? {}, method);
         }
 
         const collection = getCollectionTag(entry.routePath);