@terreno/api 0.20.1 → 0.21.0

package/dist/middleware.test.js

@@ -32,10 +32,52 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
 var Sentry = __importStar(require("@sentry/bun"));
+var express_1 = __importDefault(require("express"));
+var supertest_1 = __importDefault(require("supertest"));
 var middleware_1 = require("./middleware");
+var requestContext_1 = require("./requestContext");
 var buildReq = function (headers) {
     return {
         get: function (name) { return headers[name]; },
@@ -80,3 +122,120 @@ var buildNext = function () { return (0, bun_test_1.mock)(function () { }); };
         (0, bun_test_1.expect)(next.mock.calls[0]).toHaveLength(0);
     });
 });
+(0, bun_test_1.describe)("jsonResponseRequestIdMiddleware", function () {
+    var buildStackedApp = function () {
+        var app = (0, express_1.default)();
+        app.use(requestContext_1.requestContextMiddleware);
+        app.use(middleware_1.jsonResponseRequestIdMiddleware);
+        app.get("/object", function (_req, res) {
+            return res.json({ hello: "world" });
+        });
+        app.get("/array", function (_req, res) {
+            return res.json([1, 2]);
+        });
+        app.get("/openapi.json", function (_req, res) {
+            return res.json({ openapi: "3.0.0", paths: {} });
+        });
+        app.get("/openapi/components/schemas/Food.json", function (_req, res) {
+            return res.json({ description: "A food", type: "object" });
+        });
+        app.get("/openapi/validate", function (_req, res) {
+            return res.json({ document: { openapi: "3.0.0" }, valid: true });
+        });
+        return app;
+    };
+    (0, bun_test_1.it)("adds requestId to object JSON bodies and matches X-Request-ID header", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = buildStackedApp();
+                    return [4 /*yield*/, (0, supertest_1.default)(app).get("/object").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.hello).toBe("world");
+                    (0, bun_test_1.expect)(res.body.requestId).toBeDefined();
+                    (0, bun_test_1.expect)(res.body.requestId).toBe(res.headers["x-request-id"]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("does not wrap JSON array bodies", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = buildStackedApp();
+                    return [4 /*yield*/, (0, supertest_1.default)(app).get("/array").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body).toEqual([1, 2]);
+                    (0, bun_test_1.expect)(res.headers["x-request-id"]).toBeDefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("does not inject requestId into GET /openapi.json bodies", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = buildStackedApp();
+                    return [4 /*yield*/, (0, supertest_1.default)(app).get("/openapi.json").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body).toEqual({ openapi: "3.0.0", paths: {} });
+                    (0, bun_test_1.expect)(res.body.requestId).toBeUndefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("does not inject requestId into GET /openapi/components/...json bodies", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = buildStackedApp();
+                    return [4 /*yield*/, (0, supertest_1.default)(app).get("/openapi/components/schemas/Food.json").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body).toEqual({ description: "A food", type: "object" });
+                    (0, bun_test_1.expect)(res.body.requestId).toBeUndefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("does not inject requestId into GET /openapi/validate bodies", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = buildStackedApp();
+                    return [4 /*yield*/, (0, supertest_1.default)(app).get("/openapi/validate").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body).toEqual({ document: { openapi: "3.0.0" }, valid: true });
+                    (0, bun_test_1.expect)(res.body.requestId).toBeUndefined();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("uses incoming X-Request-ID on wrapped object responses", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = buildStackedApp();
+                    return [4 /*yield*/, (0, supertest_1.default)(app)
+                            .get("/object")
+                            .set("X-Request-ID", "client-rid-99")
+                            .expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.requestId).toBe("client-rid-99");
+                    (0, bun_test_1.expect)(res.headers["x-request-id"]).toBe("client-rid-99");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});

package/dist/openApi.test.js

@@ -70,10 +70,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
 var supertest_1 = __importDefault(require("supertest"));
 var api_1 = require("./api");
-var auth_1 = require("./auth");
-var expressServer_1 = require("./expressServer");
 var openApi_1 = require("./openApi");
 var permissions_1 = require("./permissions");
+var terrenoApp_1 = require("./terrenoApp");
 var tests_1 = require("./tests");
 function getMessageSummaryOpenApiMiddleware(options) {
     if (!options.openApi) {
@@ -136,13 +135,11 @@ function addRoutes(router, options) {
         return __generator(this, function (_a) {
             process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
             process.env.ENABLE_SWAGGER = "true";
-            app = (0, expressServer_1.setupServer)({
-                addRoutes: addRoutes,
+            app = new terrenoApp_1.TerrenoApp({
+                configureApp: addRoutes,
                 skipListen: true,
                 userModel: tests_1.UserModel,
-            });
-            (0, auth_1.setupAuth)(app, tests_1.UserModel);
-            (0, auth_1.addAuthRoutes)(app, tests_1.UserModel);
+            }).build();
             return [2 /*return*/];
         });
     }); });
@@ -342,13 +339,11 @@ function addRoutesPopulate(router, options) {
         return __generator(this, function (_a) {
             process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
             process.env.ENABLE_SWAGGER = "false";
-            app = (0, expressServer_1.setupServer)({
-                addRoutes: addRoutes,
+            app = new terrenoApp_1.TerrenoApp({
+                configureApp: addRoutes,
                 skipListen: true,
                 userModel: tests_1.UserModel,
-            });
-            (0, auth_1.setupAuth)(app, tests_1.UserModel);
-            (0, auth_1.addAuthRoutes)(app, tests_1.UserModel);
+            }).build();
             return [2 /*return*/];
         });
     }); });
@@ -371,13 +366,11 @@ function addRoutesPopulate(router, options) {
     (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
         return __generator(this, function (_a) {
             process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
-            app = (0, expressServer_1.setupServer)({
-                addRoutes: addRoutesPopulate,
+            app = new terrenoApp_1.TerrenoApp({
+                configureApp: addRoutesPopulate,
                 skipListen: true,
                 userModel: tests_1.UserModel,
-            });
-            (0, auth_1.setupAuth)(app, tests_1.UserModel);
-            (0, auth_1.addAuthRoutes)(app, tests_1.UserModel);
+            }).build();
             return [2 /*return*/];
         });
     }); });

package/dist/openApiBuilder.test.js

@@ -54,10 +54,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
 var supertest_1 = __importDefault(require("supertest"));
 var api_1 = require("./api");
-var auth_1 = require("./auth");
-var expressServer_1 = require("./expressServer");
 var openApiBuilder_1 = require("./openApiBuilder");
 var permissions_1 = require("./permissions");
+var terrenoApp_1 = require("./terrenoApp");
 var tests_1 = require("./tests");
 function addRoutesWithBuilder(router, options) {
     var _this = this;
@@ -168,13 +167,11 @@ function addRoutesWithBuilder(router, options) {
         return __generator(this, function (_a) {
             process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
             process.env.ENABLE_SWAGGER = "true";
-            app = (0, expressServer_1.setupServer)({
-                addRoutes: addRoutesWithBuilder,
+            app = new terrenoApp_1.TerrenoApp({
+                configureApp: addRoutesWithBuilder,
                 skipListen: true,
                 userModel: tests_1.UserModel,
-            });
-            (0, auth_1.setupAuth)(app, tests_1.UserModel);
-            (0, auth_1.addAuthRoutes)(app, tests_1.UserModel);
+            }).build();
             return [2 /*return*/];
         });
     }); });
@@ -367,7 +364,11 @@ function addRoutesWithBuilder(router, options) {
                         return [4 /*yield*/, server.get("/food/stats").expect(200)];
                     case 1:
                         res = _a.sent();
-                        (0, bun_test_1.expect)(res.body).toEqual({ avgCalories: 250, count: 10 });
+                        (0, bun_test_1.expect)(res.body).toEqual({
+                            avgCalories: 250,
+                            count: 10,
+                            requestId: res.headers["x-request-id"],
+                        });
                         return [2 /*return*/];
                 }
             });
@@ -384,7 +385,10 @@ function addRoutesWithBuilder(router, options) {
                                 .expect(201)];
                     case 1:
                         res = _a.sent();
-                        (0, bun_test_1.expect)(res.body).toEqual({ reportId: "report-123" });
+                        (0, bun_test_1.expect)(res.body).toEqual({
+                            reportId: "report-123",
+                            requestId: res.headers["x-request-id"],
+                        });
                         return [2 /*return*/];
                 }
             });
@@ -414,7 +418,11 @@ function addRoutesWithBuilder(router, options) {
                         return [4 /*yield*/, server.get("/food/categories/cat-123").expect(200)];
                     case 1:
                         res = _a.sent();
-                        (0, bun_test_1.expect)(res.body).toEqual({ id: "cat-123", name: "Fruits" });
+                        (0, bun_test_1.expect)(res.body).toEqual({
+                            id: "cat-123",
+                            name: "Fruits",
+                            requestId: res.headers["x-request-id"],
+                        });
                         return [2 /*return*/];
                 }
             });

package/dist/realtime/changeStreamWatcher.d.ts

@@ -21,7 +21,7 @@ export declare const mapOperationType: (operationType: string, change: ChangeStr
  * Determine which Socket.io rooms to emit to based on the room strategy.
  * Exported for testing.
  */
-export declare const resolveRooms: (entry: RealtimeRegistryEntry, doc: any, method: string) => string[];
+export declare const resolveRooms: (entry: RealtimeRegistryEntry, doc: Record<string, unknown>, method: string) => string[];
 /**
  * Ensure serialized documents include `id` to match REST API responses.
  * Change stream fullDocument payloads are raw BSON objects with `_id` only.
@@ -43,8 +43,8 @@ export declare const ensureApiId: (data: unknown) => unknown;
  * would risk leaking unsanitized fields (e.g. `hash`/`salt`) that the handler
  * was supposed to strip.
  */
-export declare const serializeDoc: (entry: RealtimeRegistryEntry, doc: any, method: "create" | "update" | "delete", user?: User) => Promise<any>;
-export declare const emitToAuthorizedRoom: (io: Server, room: string, event: RealtimeEvent, entry: RealtimeRegistryEntry, fullDocument: any, logDebug: (msg: string) => void) => Promise<void>;
+export declare const serializeDoc: (entry: RealtimeRegistryEntry, doc: Record<string, unknown>, method: "create" | "update" | "delete", user?: User) => Promise<unknown>;
+export declare const emitToAuthorizedRoom: (io: Server, room: string, event: RealtimeEvent, entry: RealtimeRegistryEntry, fullDocument: Record<string, unknown> | undefined, logDebug: (msg: string) => void) => Promise<void>;
 /**
  * Emit a sync event to document-specific and query rooms.
  *
@@ -61,7 +61,7 @@ export declare const emitToAuthorizedRoom: (io: Server, room: string, event: Rea
  *
  * Exported for testing.
  */
-export declare const emitToDocumentAndQueryRooms: (io: Server, collection: string, event: RealtimeEvent, fullDocument: any, logDebug: (msg: string) => void, entry?: RealtimeRegistryEntry) => Promise<void>;
+export declare const emitToDocumentAndQueryRooms: (io: Server, collection: string, event: RealtimeEvent, fullDocument: Record<string, unknown> | undefined, logDebug: (msg: string) => void, entry?: RealtimeRegistryEntry) => Promise<void>;
 /**
  * Start watching MongoDB change streams and emitting real-time events.
  */

package/dist/realtime/changeStreamWatcher.js

@@ -120,7 +120,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stopChangeStreamWatcher = exports.startChangeStreamWatcher = exports.emitToDocumentAndQueryRooms = exports.emitToAuthorizedRoom = exports.serializeDoc = exports.ensureApiId = exports.resolveRooms = exports.mapOperationType = void 0;
-// biome-ignore-all lint/suspicious/noExplicitAny: change stream and socket handlers use dynamic document shapes
 var Sentry = __importStar(require("@sentry/bun"));
 var luxon_1 = require("luxon");
 var mongoose_1 = __importDefault(require("mongoose"));
@@ -208,7 +207,6 @@ var canReadDocument = function (entry, user, doc) { return __awaiter(void 0, voi
  * Exported for testing.
  */
 var resolveRooms = function (entry, doc, method) {
-    var _a, _b, _c;
     var roomStrategy = entry.config.roomStrategy;
     // Use the collection tag (e.g. "todos") for model rooms, matching what the frontend subscribes to
     var collectionTag = getCollectionTag(entry.routePath);
@@ -219,7 +217,7 @@ var resolveRooms = function (entry, doc, method) {
     }
     switch (roomStrategy) {
         case "owner": {
-            var ownerId = (_c = (_b = (_a = doc === null || doc === void 0 ? void 0 : doc.ownerId) === null || _a === void 0 ? void 0 : _a.toString) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : doc === null || doc === void 0 ? void 0 : doc.ownerId;
+            var ownerId = (doc === null || doc === void 0 ? void 0 : doc.ownerId) != null ? String(doc.ownerId) : undefined;
             if (ownerId) {
                 return ["user:".concat(ownerId)];
             }
@@ -625,7 +623,7 @@ var startChangeStreamWatcher = function (io, config, debug) {
                             }
                         }
                         else {
-                            rooms = (0, exports.resolveRooms)(entry, fullDocument, method);
+                            rooms = (0, exports.resolveRooms)(entry, fullDocument !== null && fullDocument !== void 0 ? fullDocument : {}, method);
                         }
                         collection = getCollectionTag(entry.routePath);
                         event_1 = __assign({ collection: collection, id: docId, method: method, model: entry.modelName, timestamp: luxon_1.DateTime.now().toMillis() }, (change.operationType === "update" && ((_e = change.updateDescription) === null || _e === void 0 ? void 0 : _e.updatedFields)

package/dist/realtime/queryMatcher.d.ts

@@ -11,4 +11,4 @@
  * @param query - MongoDB-style query object
  * @returns true if the document matches all query conditions
  */
-export declare const matchesQuery: (doc: any, query: Record<string, any>) => boolean;
+export declare const matchesQuery: (doc: Record<string, unknown>, query: Record<string, unknown>) => boolean;

package/dist/realtime/queryMatcher.js

@@ -1,5 +1,4 @@
 "use strict";
-// 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.
@@ -63,14 +62,32 @@ var normalize = function (value) {
         return value;
     }
     // Handle ObjectId-like objects with toString
-    if (typeof value === "object" &&
-        typeof value.toString === "function" &&
-        ((_a = value.constructor) === null || _a === void 0 ? void 0 : _a.name) !== "Object" &&
-        !Array.isArray(value)) {
-        return value.toString();
+    if (typeof value === "object" && !Array.isArray(value)) {
+        var obj = value;
+        var ctorName = (_a = obj.constructor) === null || _a === void 0 ? void 0 : _a.name;
+        if (typeof obj.toString === "function" && ctorName !== "Object") {
+            return String(value);
+        }
     }
     return value;
 };
+/**
+ * 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.
+ */
+var compareValues = function (a, b) {
+    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;
+    }
+    var numA = Number(a);
+    var numB = Number(b);
+    return numA - numB;
+};
 var matchesCondition = function (rawValue, condition) {
     var e_2, _a;
     var value = normalize(rawValue);
@@ -99,26 +116,34 @@ var matchesCondition = function (rawValue, condition) {
                         return false;
                     }
                     break;
-                case "$gt":
-                    if (!(value > normOp)) {
+                case "$gt": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp <= 0) {
                         return false;
                     }
                     break;
-                case "$gte":
-                    if (!(value >= normOp)) {
+                }
+                case "$gte": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp < 0) {
                         return false;
                     }
                     break;
-                case "$lt":
-                    if (!(value < normOp)) {
+                }
+                case "$lt": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp >= 0) {
                         return false;
                     }
                     break;
-                case "$lte":
-                    if (!(value <= normOp)) {
+                }
+                case "$lte": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp > 0) {
                         return false;
                     }
                     break;
+                }
                 case "$in": {
                     if (!Array.isArray(operand)) {
                         return false;

package/dist/realtime/types.d.ts

@@ -13,9 +13,9 @@ export interface RealtimeConfig {
      * - 'broadcast': emit to all authenticated sockets
      * - function: custom room resolver returning room name(s)
      */
-    roomStrategy: "owner" | "model" | "broadcast" | ((doc: any, method: string, req: express.Request) => string[]);
+    roomStrategy: "owner" | "model" | "broadcast" | ((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;
 }
 /**
  * A real-time sync event emitted to clients via WebSocket.
@@ -94,7 +94,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/dist/requestContext.d.ts

@@ -1,15 +1,32 @@
 import type express from "express";
 import type { JwtPayload } from "jsonwebtoken";
+/**
+ * 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 declare const REQUEST_CONTEXT_ATTRIBUTE_NAMES: {
     readonly jobId: "x-job-id";
     readonly requestId: "x-request-id";
@@ -26,12 +43,56 @@ export interface JwtSessionPayload extends JwtPayload {
 }
 export declare const getSessionIdFromJwtPayload: (payload?: JwtSessionPayload | null) => string | undefined;
 export declare const getRequestContextFromAttributes: (attributes?: Record<string, string | undefined>) => RequestContext;
+/**
+ * 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 declare const getCurrentRequestContext: () => RequestContext | undefined;
+/**
+ * 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 declare const getCurrentLogContext: () => Partial<RequestContext>;
 export declare const applyRequestContextToSentry: (context?: Partial<RequestContext>) => void;
 export declare const setRequestContext: (updates: Partial<RequestContext>) => void;
+/**
+ * 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 declare const getCurrentRequestContextAttributes: (overrides?: Partial<RequestContext>) => RequestContextAttributes;
+/**
+ * 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 declare const runWithRequestContext: <T>(context: Partial<RequestContext>, callback: () => T) => 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 declare const runWithRequestContextAttributes: <T>(attributes: Record<string, string | undefined> | undefined, callback: () => T) => T;
 export declare const updateRequestContextFromRequest: (req: express.Request, res?: express.Response) => void;
+/**
+ * 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 declare const requestContextMiddleware: (req: express.Request, res: express.Response, next: express.NextFunction) => void;