@terreno/api 0.20.2 → 0.21.0

package/dist/requestContext.js

@@ -72,6 +72,31 @@ var __values = (this && this.__values) || function(o) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestContextMiddleware = exports.updateRequestContextFromRequest = exports.runWithRequestContextAttributes = exports.runWithRequestContext = exports.getCurrentRequestContextAttributes = exports.setRequestContext = exports.applyRequestContextToSentry = exports.getCurrentLogContext = exports.getCurrentRequestContext = exports.getRequestContextFromAttributes = exports.getSessionIdFromJwtPayload = exports.REQUEST_CONTEXT_ATTRIBUTE_NAMES = void 0;
+/**
+ * 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
+ */
 var node_async_hooks_1 = require("node:async_hooks");
 var node_crypto_1 = require("node:crypto");
 var Sentry = __importStar(require("@sentry/bun"));
@@ -84,6 +109,11 @@ var TRACE_ID_HEADER = "x-trace-id";
 var TRACE_PARENT_HEADER = "traceparent";
 var TRACE_SAMPLED_HEADER = "x-trace-sampled";
 var USER_ID_HEADER = "x-user-id";
+/**
+ * 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}).
+ */
 exports.REQUEST_CONTEXT_ATTRIBUTE_NAMES = {
     jobId: JOB_ID_HEADER,
     requestId: "x-request-id",
@@ -193,10 +223,19 @@ var getRequestContextFromAttributes = function (attributes) {
     };
 };
 exports.getRequestContextFromAttributes = 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.
+ */
 var getCurrentRequestContext = function () {
     return requestContextStorage.getStore();
 };
 exports.getCurrentRequestContext = getCurrentRequestContext;
+/**
+ * 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.
+ */
 var getCurrentLogContext = function () {
     var context = (0, exports.getCurrentRequestContext)();
     if (!context) {
@@ -266,6 +305,11 @@ var setAttribute = function (attributes, name, value) {
     }
     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.
+ */
 var getCurrentRequestContextAttributes = function (overrides) {
     if (overrides === void 0) { overrides = {}; }
     var context = __assign(__assign({}, (0, exports.getCurrentLogContext)()), overrides);
@@ -280,6 +324,23 @@ var getCurrentRequestContextAttributes = function (overrides) {
     return attributes;
 };
 exports.getCurrentRequestContextAttributes = getCurrentRequestContextAttributes;
+/**
+ * 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();
+ * });
+ * ```
+ */
 var runWithRequestContext = function (context, callback) {
     var _a;
     var nextContext = __assign(__assign({}, context), { requestId: (_a = context.requestId) !== null && _a !== void 0 ? _a : (0, node_crypto_1.randomUUID)() });
@@ -289,6 +350,11 @@ var runWithRequestContext = function (context, callback) {
     });
 };
 exports.runWithRequestContext = runWithRequestContext;
+/**
+ * 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}.
+ */
 var runWithRequestContextAttributes = function (attributes, callback) {
     if (attributes === void 0) { attributes = {}; }
     return (0, exports.runWithRequestContext)((0, exports.getRequestContextFromAttributes)(attributes), callback);
@@ -312,6 +378,14 @@ var updateRequestContextFromRequest = function (req, res) {
     }
 };
 exports.updateRequestContextFromRequest = 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`.
+ */
 var requestContextMiddleware = function (req, res, next) {
     var cloudTraceContext = parseGoogleCloudTraceContext(getHeader(req, CLOUD_TRACE_CONTEXT_HEADER));
     var traceParentContext = parseTraceParent(getHeader(req, TRACE_PARENT_HEADER));

package/dist/secretProviders.test.js

@@ -37,6 +37,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
+var errors_1 = require("./errors");
 var secretProviders_1 = require("./secretProviders");
 (0, bun_test_1.describe)("EnvSecretProvider", function () {
     (0, bun_test_1.beforeEach)(function () {
@@ -389,3 +390,337 @@ var secretProviders_1 = require("./secretProviders");
         });
     }); });
 });
+/** Inject a pre-built mock client into a GcpSecretProvider, bypassing getClient(). */
+var injectClient = function (provider, client) {
+    // Bypass the private `client` field for testing — avoids the dynamic import of
+    // @google-cloud/secret-manager which is an optional peer dependency.
+    Object.defineProperty(provider, "client", { configurable: true, value: client, writable: true });
+};
+(0, bun_test_1.describe)("GcpSecretProvider", function () {
+    (0, bun_test_1.it)("has the name 'gcp'", function () {
+        var provider = new secretProviders_1.GcpSecretProvider({ projectId: "my-project" });
+        (0, bun_test_1.expect)(provider.name).toBe("gcp");
+    });
+    (0, bun_test_1.it)("throws APIError when @google-cloud/secret-manager is not installed", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var provider, error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "my-project" });
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, provider.getSecret("some-secret")];
+                case 2:
+                    _a.sent();
+                    bun_test_1.expect.unreachable("should have thrown");
+                    return [3 /*break*/, 4];
+                case 3:
+                    error_1 = _a.sent();
+                    (0, bun_test_1.expect)(error_1).toBeInstanceOf(errors_1.APIError);
+                    (0, bun_test_1.expect)(error_1.title).toContain("GcpSecretProvider requires @google-cloud/secret-manager");
+                    return [3 /*break*/, 4];
+                case 4: return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("resolves a short secret name to the full resource path with default version", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var calls, mockClient, provider, result;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    calls = [];
+                    mockClient = {
+                        accessSecretVersion: function (req) { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                calls.push(req.name);
+                                return [2 /*return*/, [{ payload: { data: "secret-value" } }]];
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "my-project" });
+                    injectClient(provider, mockClient);
+                    return [4 /*yield*/, provider.getSecret("openai-api-key")];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result).toBe("secret-value");
+                    (0, bun_test_1.expect)(calls).toEqual(["projects/my-project/secrets/openai-api-key/versions/latest"]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("resolves a short secret name with an explicit version", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var calls, mockClient, provider, result;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    calls = [];
+                    mockClient = {
+                        accessSecretVersion: function (req) { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                calls.push(req.name);
+                                return [2 /*return*/, [{ payload: { data: "v3-value" } }]];
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    return [4 /*yield*/, provider.getSecret("my-key", "3")];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result).toBe("v3-value");
+                    (0, bun_test_1.expect)(calls).toEqual(["projects/p/secrets/my-key/versions/3"]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("honors a full resource path that already contains /versions/", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var calls, mockClient, provider, result;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    calls = [];
+                    mockClient = {
+                        accessSecretVersion: function (req) { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                calls.push(req.name);
+                                return [2 /*return*/, [{ payload: { data: "pinned" } }]];
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "ignored" });
+                    injectClient(provider, mockClient);
+                    return [4 /*yield*/, provider.getSecret("projects/p/secrets/s/versions/7")];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result).toBe("pinned");
+                    (0, bun_test_1.expect)(calls).toEqual(["projects/p/secrets/s/versions/7"]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("appends /versions/latest to a full resource path without a version suffix", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var calls, mockClient, provider, result;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    calls = [];
+                    mockClient = {
+                        accessSecretVersion: function (req) { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                calls.push(req.name);
+                                return [2 /*return*/, [{ payload: { data: "latest-value" } }]];
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "ignored" });
+                    injectClient(provider, mockClient);
+                    return [4 /*yield*/, provider.getSecret("projects/p/secrets/s")];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result).toBe("latest-value");
+                    (0, bun_test_1.expect)(calls).toEqual(["projects/p/secrets/s/versions/latest"]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("appends the explicit version when full path lacks /versions/", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var calls, mockClient, provider, result;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    calls = [];
+                    mockClient = {
+                        accessSecretVersion: function (req) { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                calls.push(req.name);
+                                return [2 /*return*/, [{ payload: { data: "v5" } }]];
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "ignored" });
+                    injectClient(provider, mockClient);
+                    return [4 /*yield*/, provider.getSecret("projects/p/secrets/s", "5")];
+                case 1:
+                    result = _a.sent();
+                    (0, bun_test_1.expect)(result).toBe("v5");
+                    (0, bun_test_1.expect)(calls).toEqual(["projects/p/secrets/s/versions/5"]);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("decodes a Uint8Array payload", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var encoded, mockClient, provider, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    encoded = new TextEncoder().encode("binary-secret");
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, [{ payload: { data: encoded } }]];
+                        }); }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a = bun_test_1.expect;
+                    return [4 /*yield*/, provider.getSecret("bin-key")];
+                case 1:
+                    _a.apply(void 0, [_b.sent()]).toBe("binary-secret");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns null when the payload is empty", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var mockClient, provider, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, [{ payload: {} }]];
+                        }); }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a = bun_test_1.expect;
+                    return [4 /*yield*/, provider.getSecret("empty-payload")];
+                case 1:
+                    _a.apply(void 0, [_b.sent()]).toBeNull();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns null when the payload field is missing entirely", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var mockClient, provider, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, [{}]];
+                        }); }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a = bun_test_1.expect;
+                    return [4 /*yield*/, provider.getSecret("no-payload")];
+                case 1:
+                    _a.apply(void 0, [_b.sent()]).toBeNull();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns null on NOT_FOUND (gRPC code 5)", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var notFound, mockClient, provider, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    notFound = Object.assign(new Error("NOT_FOUND"), { code: 5 });
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                throw notFound;
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a = bun_test_1.expect;
+                    return [4 /*yield*/, provider.getSecret("missing-secret")];
+                case 1:
+                    _a.apply(void 0, [_b.sent()]).toBeNull();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("re-throws non-NOT_FOUND errors", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var permissionDenied, mockClient, provider, error_2;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    permissionDenied = Object.assign(new Error("PERMISSION_DENIED"), { code: 7 });
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                throw permissionDenied;
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, provider.getSecret("forbidden-secret")];
+                case 2:
+                    _a.sent();
+                    bun_test_1.expect.unreachable("should have thrown");
+                    return [3 /*break*/, 4];
+                case 3:
+                    error_2 = _a.sent();
+                    (0, bun_test_1.expect)(error_2).toBe(permissionDenied);
+                    return [3 /*break*/, 4];
+                case 4: return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("re-throws non-Error throwables", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var mockClient, provider, error_3;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                throw "string-error";
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, provider.getSecret("x")];
+                case 2:
+                    _a.sent();
+                    bun_test_1.expect.unreachable("should have thrown");
+                    return [3 /*break*/, 4];
+                case 3:
+                    error_3 = _a.sent();
+                    (0, bun_test_1.expect)(error_3).toBe("string-error");
+                    return [3 /*break*/, 4];
+                case 4: return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("caches the client across multiple getSecret calls", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var callCount, mockClient, provider, _a, _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    callCount = 0;
+                    mockClient = {
+                        accessSecretVersion: function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                callCount++;
+                                return [2 /*return*/, [{ payload: { data: "call-".concat(callCount) } }]];
+                            });
+                        }); },
+                    };
+                    provider = new secretProviders_1.GcpSecretProvider({ projectId: "p" });
+                    injectClient(provider, mockClient);
+                    _a = bun_test_1.expect;
+                    return [4 /*yield*/, provider.getSecret("a")];
+                case 1:
+                    _a.apply(void 0, [_c.sent()]).toBe("call-1");
+                    _b = bun_test_1.expect;
+                    return [4 /*yield*/, provider.getSecret("b")];
+                case 2:
+                    _b.apply(void 0, [_c.sent()]).toBe("call-2");
+                    (0, bun_test_1.expect)(callCount).toBe(2);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});

package/dist/terrenoApp.d.ts

@@ -3,7 +3,7 @@ import express from "express";
 import type { ModelRouterRegistration } from "./api";
 import { type UserModel as UserMongooseModel } from "./auth";
 import { type ConfigurationAppOptions } from "./configurationApp";
-import { type AuthOptions } from "./expressServer";
+import { type AddRoutes, type AuthOptions } from "./expressServer";
 import { type GitHubAuthOptions } from "./githubAuth";
 import { type LoggingOptions } from "./logger";
 import type { RealtimeAppOptions } from "./realtime/types";
@@ -38,27 +38,40 @@ export interface TerrenoAppOptions {
      * Set to `true` for defaults, or pass a RealtimeAppOptions object for full control.
      */
     realtime?: boolean | RealtimeAppOptions;
+    /**
+     * Runs after CORS and before the `addMiddleware` chain and JSON body parsing.
+     * Use to attach early middleware via `app.use(...)` before JSON parsing.
+     */
+    beforeJsonSetup?: (app: express.Application) => void;
+    /**
+     * Invoked after registered plugins/model routers and before `/auth/me`.
+     * Receives the Express app and OpenAPI bundle for `modelRouter` / `createOpenApiBuilder` wiring.
+     */
+    configureApp?: AddRoutes;
 }
 /**
  * Fluent API for building Express applications with Terreno framework.
  *
- * TerrenoApp provides an alternative to `setupServer` using a registration
- * pattern instead of callbacks. Build applications by registering model
- * routers and plugins, then calling `start()` to begin listening.
+ * TerrenoApp is the supported way to assemble the Terreno Express stack.
+ * Build applications by registering model routers and plugins (and/or
+ * `configureApp`), then calling `start()` to listen.
  *
  * The middleware stack is configured in this order:
  * 1. CORS
- * 2. Custom middleware (via addMiddleware)
- * 3. JSON body parser
- * 4. Auth routes (/auth/login, /auth/signup, etc.)
- * 5. JWT authentication setup
- * 6. Request logging
- * 7. Sentry scopes
- * 8. OpenAPI middleware
- * 9. /auth/me routes
+ * 2. Optional `beforeJsonSetup` (configure the app before JSON parsing)
+ * 3. Custom middleware (via addMiddleware)
+ * 4. JSON body parser
+ * 5. Auth routes (/auth/login, /auth/signup, etc.)
+ * 6. JWT authentication setup
+ * 7. Request logging
+ * 8. Sentry scopes
+ * 9. OpenAPI middleware (including JSON `requestId` on object responses)
  * 10. GitHub OAuth routes (if enabled)
- * 11. Registered model routers and plugins
- * 12. Error handling middleware
+ * 11. Configuration app (if any)
+ * 12. Registered model routers and plugins
+ * 13. Optional `configureApp` callback
+ * 14. /auth/me routes
+ * 15. Error handling middleware
  *
  * @example
  * ```typescript
@@ -95,7 +108,6 @@ export interface TerrenoAppOptions {
  *   .start();
  * ```
  *
- * @see setupServer for the callback-based alternative
  * @see TerrenoPlugin for creating reusable plugins
  * @see modelRouter for creating CRUD route registrations
  */

package/dist/terrenoApp.js

@@ -70,6 +70,7 @@ var errors_1 = require("./errors");
 var expressServer_1 = require("./expressServer");
 var githubAuth_1 = require("./githubAuth");
 var logger_1 = require("./logger");
+var middleware_1 = require("./middleware");
 var openApiCompat_1 = require("./openApiCompat");
 var openApiEtag_1 = require("./openApiEtag");
 var realtimeApp_1 = require("./realtime/realtimeApp");
@@ -78,23 +79,26 @@ var index_1 = __importDefault(require("./vendor/wesleytodd-openapi/index"));
 /**
  * Fluent API for building Express applications with Terreno framework.
  *
- * TerrenoApp provides an alternative to `setupServer` using a registration
- * pattern instead of callbacks. Build applications by registering model
- * routers and plugins, then calling `start()` to begin listening.
+ * TerrenoApp is the supported way to assemble the Terreno Express stack.
+ * Build applications by registering model routers and plugins (and/or
+ * `configureApp`), then calling `start()` to listen.
  *
  * The middleware stack is configured in this order:
  * 1. CORS
- * 2. Custom middleware (via addMiddleware)
- * 3. JSON body parser
- * 4. Auth routes (/auth/login, /auth/signup, etc.)
- * 5. JWT authentication setup
- * 6. Request logging
- * 7. Sentry scopes
- * 8. OpenAPI middleware
- * 9. /auth/me routes
+ * 2. Optional `beforeJsonSetup` (configure the app before JSON parsing)
+ * 3. Custom middleware (via addMiddleware)
+ * 4. JSON body parser
+ * 5. Auth routes (/auth/login, /auth/signup, etc.)
+ * 6. JWT authentication setup
+ * 7. Request logging
+ * 8. Sentry scopes
+ * 9. OpenAPI middleware (including JSON `requestId` on object responses)
  * 10. GitHub OAuth routes (if enabled)
- * 11. Registered model routers and plugins
- * 12. Error handling middleware
+ * 11. Configuration app (if any)
+ * 12. Registered model routers and plugins
+ * 13. Optional `configureApp` callback
+ * 14. /auth/me routes
+ * 15. Error handling middleware
  *
  * @example
  * ```typescript
@@ -131,7 +135,6 @@ var index_1 = __importDefault(require("./vendor/wesleytodd-openapi/index"));
  *   .start();
  * ```
  *
- * @see setupServer for the callback-based alternative
  * @see TerrenoPlugin for creating reusable plugins
  * @see modelRouter for creating CRUD route registrations
  */
@@ -254,6 +257,9 @@ var TerrenoApp = /** @class */ (function () {
         app.set("query parser", function (str) { var _a; return qs_1.default.parse(str, { arrayLimit: (_a = options.arrayLimit) !== null && _a !== void 0 ? _a : 200 }); });
         app.use(requestContext_1.requestContextMiddleware);
         app.use((0, cors_1.default)({ credentials: true, origin: (_c = options.corsOrigin) !== null && _c !== void 0 ? _c : "*" }));
+        if (options.beforeJsonSetup) {
+            options.beforeJsonSetup(app);
+        }
         try {
             // Apply custom middleware before JSON parsing
             for (var _d = __values(this.middlewareFns), _e = _d.next(); !_e.done; _e = _d.next()) {
@@ -314,6 +320,7 @@ var TerrenoApp = /** @class */ (function () {
         // OpenAPI
         app.use(openApiCompat_1.openApiCompatMiddleware);
         app.use(openApiEtag_1.openApiEtagMiddleware);
+        app.use(middleware_1.jsonResponseRequestIdMiddleware);
         var oapi = (0, index_1.default)({
             info: {
                 description: "Generated docs from an Express api",
@@ -355,6 +362,9 @@ var TerrenoApp = /** @class */ (function () {
             }
             finally { if (e_2) throw e_2.error; }
         }
+        if (options.configureApp) {
+            options.configureApp(app, { openApi: oapi });
+        }
         // /auth/me must be registered after plugins so that session middleware
         // (e.g. Better Auth) has a chance to populate req.user first.
         (0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions);