@terreno/api 0.20.2 → 0.21.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/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 {
@@ -145,13 +144,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", () => {
@@ -302,7 +299,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 +312,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 +329,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/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);

package/src/realtime/queryMatcher.ts

@@ -1,4 +1,3 @@
-// biome-ignore-all lint/suspicious/noExplicitAny: MongoDB query matcher evaluates dynamic filter shapes
 /**
  * Simple in-memory MongoDB query matcher.
  * Evaluates a MongoDB-style query object against a document without hitting the database.
@@ -6,35 +5,52 @@
  * Supports: equality, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or, $not.
  */
 
-const getNestedValue = (doc: any, path: string): any => {
+const getNestedValue = (doc: Record<string, unknown>, path: string): unknown => {
   const parts = path.split(".");
-  let current = doc;
+  let current: unknown = doc;
   for (const part of parts) {
     if (current === null || current === undefined) {
       return undefined;
     }
-    current = current[part];
+    current = (current as Record<string, unknown>)[part];
   }
   return current;
 };
 
-const normalize = (value: any): any => {
+const normalize = (value: unknown): unknown => {
   if (value === null || value === undefined) {
     return value;
   }
   // Handle ObjectId-like objects with toString
-  if (
-    typeof value === "object" &&
-    typeof value.toString === "function" &&
-    value.constructor?.name !== "Object" &&
-    !Array.isArray(value)
-  ) {
-    return value.toString();
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    const ctorName = (obj.constructor as {name?: string} | undefined)?.name;
+    if (typeof obj.toString === "function" && ctorName !== "Object") {
+      return String(value);
+    }
   }
   return value;
 };
 
-const matchesCondition = (rawValue: any, condition: any): boolean => {
+/**
+ * JS abstract relational comparison on unknown values.
+ * Numeric operands compare numerically; everything else compares as strings.
+ * This mirrors the coercion behaviour of `>` / `<` on the `any`-typed values
+ * that MongoDB in-memory matching historically received.
+ */
+const compareValues = (a: unknown, b: unknown): number => {
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  const numA = Number(a);
+  const numB = Number(b);
+  return numA - numB;
+};
+
+const matchesCondition = (rawValue: unknown, condition: unknown): boolean => {
   const value = normalize(rawValue);
 
   // Direct equality (non-object condition)
@@ -49,7 +65,7 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
   }
 
   // Operator object
-  for (const [op, operand] of Object.entries(condition)) {
+  for (const [op, operand] of Object.entries(condition as Record<string, unknown>)) {
     const normOp = normalize(operand);
 
     switch (op) {
@@ -63,32 +79,40 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
           return false;
         }
         break;
-      case "$gt":
-        if (!(value > normOp)) {
+      case "$gt": {
+        const cmp = compareValues(value, normOp);
+        if (Number.isNaN(cmp) || cmp <= 0) {
           return false;
         }
         break;
-      case "$gte":
-        if (!(value >= normOp)) {
+      }
+      case "$gte": {
+        const cmp = compareValues(value, normOp);
+        if (Number.isNaN(cmp) || cmp < 0) {
           return false;
         }
         break;
-      case "$lt":
-        if (!(value < normOp)) {
+      }
+      case "$lt": {
+        const cmp = compareValues(value, normOp);
+        if (Number.isNaN(cmp) || cmp >= 0) {
           return false;
         }
         break;
-      case "$lte":
-        if (!(value <= normOp)) {
+      }
+      case "$lte": {
+        const cmp = compareValues(value, normOp);
+        if (Number.isNaN(cmp) || cmp > 0) {
           return false;
         }
         break;
+      }
       case "$in": {
         if (!Array.isArray(operand)) {
           return false;
         }
         const inValues = operand.map(normalize);
-        if (!inValues.some((v: any) => v === value || String(v) === String(value))) {
+        if (!inValues.some((v) => v === value || String(v) === String(value))) {
           return false;
         }
         break;
@@ -98,7 +122,7 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
           return false;
         }
         const ninValues = operand.map(normalize);
-        if (ninValues.some((v: any) => v === value || String(v) === String(value))) {
+        if (ninValues.some((v) => v === value || String(v) === String(value))) {
           return false;
         }
         break;
@@ -132,14 +156,17 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
  * @param query - MongoDB-style query object
  * @returns true if the document matches all query conditions
  */
-export const matchesQuery = (doc: any, query: Record<string, any>): boolean => {
+export const matchesQuery = (
+  doc: Record<string, unknown>,
+  query: Record<string, unknown>
+): boolean => {
   for (const [key, condition] of Object.entries(query)) {
     if (key === "$and") {
       if (!Array.isArray(condition)) {
         return false;
       }
       for (const subQuery of condition) {
-        if (!matchesQuery(doc, subQuery)) {
+        if (!matchesQuery(doc, subQuery as Record<string, unknown>)) {
           return false;
         }
       }
@@ -152,7 +179,7 @@ export const matchesQuery = (doc: any, query: Record<string, any>): boolean => {
       }
       let matched = false;
       for (const subQuery of condition) {
-        if (matchesQuery(doc, subQuery)) {
+        if (matchesQuery(doc, subQuery as Record<string, unknown>)) {
           matched = true;
           break;
         }

package/src/realtime/types.ts

@@ -1,4 +1,3 @@
-// biome-ignore-all lint/suspicious/noExplicitAny: realtime config callbacks receive dynamic document shapes
 import type express from "express";
 
 /**
@@ -19,9 +18,9 @@ export interface RealtimeConfig {
     | "owner"
     | "model"
     | "broadcast"
-    | ((doc: any, method: string, req: express.Request) => string[]);
+    | ((doc: Record<string, unknown>, method: string, req: express.Request) => string[]);
   /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
-  realtimeResponseHandler?: (doc: any, method: string) => any;
+  realtimeResponseHandler?: (doc: Record<string, unknown>, method: string) => unknown;
 }
 
 /**
@@ -37,6 +36,7 @@ export interface RealtimeEvent {
   /** Document ID */
   id: string;
   /** Serialized document data (omitted for hard deletes) */
+  // biome-ignore lint/suspicious/noExplicitAny: noExplicitAny: event data is a serialized document whose shape varies by model; consumers must narrow to their specific type
   data?: any;
   /** Fields that were updated (for update events from change streams) */
   updatedFields?: string[];
@@ -102,7 +102,7 @@ export interface QuerySubscription {
   /** Collection tag (e.g. "todos") */
   collection: string;
   /** MongoDB-style query filter (e.g. {completed: false}) */
-  query: Record<string, any>;
+  query: Record<string, unknown>;
   /** Client-provided queryId (ignored — server computes a canonical ID) */
   queryId?: string;
 }

package/src/requestContext.ts

@@ -1,3 +1,28 @@
+/**
+ * Request/job correlation for `@terreno/api`.
+ *
+ * Correlation is how every log line emitted while handling one request (or one background job) can
+ * be tied back together. It is built on Node's {@link AsyncLocalStorage}: a {@link RequestContext}
+ * (with `requestId`, `userId`, `traceId`, etc.) is stored for the duration of a callback, and the
+ * logger's Winston format reads it from there and merges it into each line. Nothing needs to be
+ * threaded through function arguments.
+ *
+ * Two ways a scope is established:
+ *
+ * - **HTTP**: {@link requestContextMiddleware} runs first in the middleware stack. It derives a
+ *   `requestId` from incoming headers ({@link REQUEST_CONTEXT_ATTRIBUTE_NAMES}, `x-correlation-id`,
+ *   Cloud Trace, or W3C `traceparent`) or generates one, echoes it back as `X-Request-ID`, and runs
+ *   the rest of the request inside the scope.
+ * - **Jobs/scripts**: {@link runWithRequestContext} (or {@link runWithRequestContextAttributes})
+ *   establishes the same scope manually so background work is just as traceable.
+ *
+ * The active context is also pushed to Sentry tags/context via {@link applyRequestContextToSentry},
+ * and is exposed to logging via {@link getCurrentLogContext} / {@link getCurrentRequestContext}.
+ *
+ * @see {@link runWithRequestContext}
+ * @see {@link getCurrentLogContext}
+ * @module requestContext
+ */
 import {AsyncLocalStorage} from "node:async_hooks";
 import {randomUUID} from "node:crypto";
 import * as Sentry from "@sentry/bun";
@@ -14,18 +39,35 @@ const TRACE_PARENT_HEADER = "traceparent";
 const TRACE_SAMPLED_HEADER = "x-trace-sampled";
 const USER_ID_HEADER = "x-user-id";
 
+/**
+ * Correlation fields stored in AsyncLocalStorage for the lifetime of a request or job. Every log
+ * line emitted inside the scope is enriched with these. `requestId` is the only required field; the
+ * rest are populated when headers, trace context, or auth supply them.
+ */
 export interface RequestContext {
+  /** Background job identifier (from `x-job-id` or set via {@link runWithRequestContext}). */
   jobId?: string;
+  /** Stable id shared by all log lines for one request/job; echoed to clients as `X-Request-ID`. */
   requestId: string;
+  /** Auth session id, resolved from the JWT/Better Auth session or `x-session-id`. */
   sessionId?: string;
+  /** Distributed-tracing span id, parsed from Cloud Trace or W3C `traceparent`. */
   spanId?: string;
+  /** Distributed-tracing trace id, parsed from Cloud Trace or W3C `traceparent`. */
   traceId?: string;
+  /** Whether the trace is sampled, per the incoming trace headers. */
   traceSampled?: boolean;
+  /** Authenticated user id, populated after auth middleware runs. */
   userId?: string;
 }
 
 export type RequestContextAttributes = Record<string, string>;
 
+/**
+ * Canonical HTTP header names for each correlation field. Use these to propagate context to
+ * downstream services (pair with {@link getCurrentRequestContextAttributes}) or to read it from an
+ * incoming request (pair with {@link getRequestContextFromAttributes}).
+ */
 export const REQUEST_CONTEXT_ATTRIBUTE_NAMES = {
   jobId: JOB_ID_HEADER,
   requestId: "x-request-id",
@@ -161,10 +203,19 @@ export const getRequestContextFromAttributes = (
   };
 };
 
+/**
+ * Returns the full {@link RequestContext} for the active AsyncLocalStorage scope, or `undefined`
+ * when called outside any request/job scope. The logger uses this to enrich each line.
+ */
 export const getCurrentRequestContext = (): RequestContext | undefined => {
   return requestContextStorage.getStore();
 };
 
+/**
+ * Returns the active correlation fields as a plain object (empty when outside a scope). This is the
+ * shape attached to Sentry log attributes and is handy when you need to log or forward the current
+ * context yourself.
+ */
 export const getCurrentLogContext = (): Partial<RequestContext> => {
   const context = getCurrentRequestContext();
   if (!context) {
@@ -254,6 +305,11 @@ const setAttribute = (
   attributes[name] = String(value);
 };
 
+/**
+ * Serializes the active correlation context into HTTP header attributes (keyed by
+ * {@link REQUEST_CONTEXT_ATTRIBUTE_NAMES}) so it can be propagated on outbound requests to other
+ * services, keeping the same `requestId`/`traceId` across service boundaries.
+ */
 export const getCurrentRequestContextAttributes = (
   overrides: Partial<RequestContext> = {}
 ): RequestContextAttributes => {
@@ -269,6 +325,23 @@ export const getCurrentRequestContextAttributes = (
   return attributes;
 };
 
+/**
+ * Runs `callback` inside a fresh correlation scope so every log line it emits shares the same
+ * identifiers — the manual equivalent of {@link requestContextMiddleware} for background jobs,
+ * cron tasks, scripts, queue consumers, etc. A `requestId` is generated when not supplied, and the
+ * context is mirrored to Sentry.
+ *
+ * @example
+ * ```typescript
+ * import {createScopedLogger, runWithRequestContext} from "@terreno/api";
+ *
+ * await runWithRequestContext({jobId: "nightly-sync"}, async () => {
+ *   const log = createScopedLogger({prefix: "[NightlySync]"});
+ *   log.info("started"); // includes jobId + a generated requestId on every line
+ *   await sync();
+ * });
+ * ```
+ */
 export const runWithRequestContext = <T>(
   context: Partial<RequestContext>,
   callback: () => T
@@ -284,6 +357,11 @@ export const runWithRequestContext = <T>(
   });
 };
 
+/**
+ * Like {@link runWithRequestContext}, but seeds the scope from raw header attributes (for example
+ * those received on an incoming message or forwarded by another service). Parses Cloud Trace / W3C
+ * `traceparent` into `traceId`/`spanId` via {@link getRequestContextFromAttributes}.
+ */
 export const runWithRequestContextAttributes = <T>(
   attributes: Record<string, string | undefined> = {},
   callback: () => T
@@ -324,6 +402,14 @@ export const updateRequestContextFromRequest = (
   }
 };
 
+/**
+ * Express middleware that opens a correlation scope for the request. Mounted early by `TerrenoApp` /
+ * `setupServer`, it resolves a `requestId` (from request-id/correlation headers, Cloud Trace, or
+ * W3C `traceparent`, else a new UUID), captures any `jobId`/`sessionId`/trace fields, echoes
+ * `X-Request-ID` back to the client, and runs the remaining middleware inside the scope so all
+ * downstream logs are correlated. A later auth-aware pass ({@link updateRequestContextFromRequest})
+ * fills in `userId`/`sessionId`.
+ */
 export const requestContextMiddleware = (
   req: express.Request,
   res: express.Response,