@terreno/api 0.13.2 → 0.14.0

package/dist/logger.js

@@ -83,50 +83,70 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = exports.winstonLogger = void 0;
-exports.setupLogging = setupLogging;
+exports.setupLogging = exports.logger = exports.winstonLogger = void 0;
 var node_fs_1 = __importDefault(require("node:fs"));
 var node_util_1 = require("node:util");
 var Sentry = __importStar(require("@sentry/bun"));
 var winston_1 = __importDefault(require("winston"));
-function isPrimitive(val) {
+var requestContext_1 = require("./requestContext");
+var isPrimitive = function (val) {
     return val === null || (typeof val !== "object" && typeof val !== "function");
-}
-function formatWithInspect(val) {
+};
+var formatWithInspect = function (val) {
     var prefix = isPrimitive(val) ? "" : "\n";
     var shouldFormat = typeof val !== "string";
     return prefix + (shouldFormat ? (0, node_util_1.inspect)(val, { colors: true, depth: null }) : val);
-}
+};
+var addRequestContextFormat = winston_1.default.format(function (info) {
+    var context = (0, requestContext_1.getCurrentLogContext)();
+    return __assign(__assign({}, context), info);
+});
+var formatContext = function (info) {
+    var contextParts = [
+        info.requestId ? "requestId=".concat(info.requestId) : undefined,
+        info.jobId ? "jobId=".concat(info.jobId) : undefined,
+        info.sessionId ? "sessionId=".concat(info.sessionId) : undefined,
+        info.userId ? "userId=".concat(info.userId) : undefined,
+        info.traceId ? "traceId=".concat(info.traceId) : undefined,
+    ].filter(Boolean);
+    if (contextParts.length === 0) {
+        return "";
+    }
+    return " ".concat(contextParts.join(" "));
+};
 // Winston doesn't operate like console.log by default, e.g. `logger.error('error',
 // error)` only prints the message and no args. Add handling for all the args,
 // while also supporting splat logging.
-function printf(timestamp) {
+var printf = function (timestamp) {
     if (timestamp === void 0) { timestamp = false; }
     return function (info) {
         var msg = formatWithInspect(info.message);
-        var splatArgs = (info[Symbol.for("splat")] || []);
+        var splatKey = Symbol.for("splat");
+        var splatArgs = (info[splatKey] || []);
         var rest = splatArgs.map(function (data) { return formatWithInspect(data); }).join(" ");
+        var context = formatContext(info);
         if (timestamp) {
-            return "".concat(info.timestamp, " - ").concat(info.level, ": ").concat(msg, " ").concat(rest);
+            return "".concat(info.timestamp, " - ").concat(info.level, ": ").concat(msg).concat(context, " ").concat(rest);
         }
-        return "".concat(info.level, ": ").concat(msg, " ").concat(rest);
+        return "".concat(info.level, ": ").concat(msg).concat(context, " ").concat(rest);
     };
-}
+};
 // Setup a global, default rejection handler.
 winston_1.default.add(new winston_1.default.transports.Console({
     debugStdout: true,
-    format: winston_1.default.format.combine(winston_1.default.format.colorize(), winston_1.default.format.simple(), winston_1.default.format.printf(printf(false))),
+    format: winston_1.default.format.combine(addRequestContextFormat(), winston_1.default.format.colorize(), winston_1.default.format.simple(), winston_1.default.format.printf(printf(false))),
     handleExceptions: true,
     handleRejections: true,
     level: "error",
 }));
 // Setup a default console logger.
 exports.winstonLogger = winston_1.default.createLogger({
+    format: addRequestContextFormat(),
     level: "debug",
     transports: [
         new winston_1.default.transports.Console({
             debugStdout: true,
-            format: winston_1.default.format.combine(winston_1.default.format.colorize(), winston_1.default.format.simple(), winston_1.default.format.printf(printf(false))),
+            format: winston_1.default.format.combine(addRequestContextFormat(), winston_1.default.format.colorize(), winston_1.default.format.simple(), winston_1.default.format.printf(printf(false))),
             handleExceptions: true,
             handleRejections: true,
             level: "debug",
@@ -134,11 +154,12 @@ exports.winstonLogger = winston_1.default.createLogger({
     ],
 });
 // Helper function to send logs to Sentry if enabled
-function sendToSentry(message, level) {
+var sendToSentry = function (message, level) {
     if (process.env.USE_SENTRY_LOGGING === "true" && Sentry.logger) {
-        Sentry.logger[level](message);
+        var logWithContext = Sentry.logger[level];
+        logWithContext(message, (0, requestContext_1.getCurrentLogContext)());
     }
-}
+};
 exports.logger = {
     // simple way to log a caught exception. e.g. promise().catch(logger.catch)
     catch: function (e) {
@@ -186,12 +207,12 @@ exports.logger = {
         sendToSentry(msg, "warn");
     },
 };
-function setupLogging(options) {
+var setupLogging = function (options) {
     var _a, e_1, _b;
     var _c, _d;
     exports.winstonLogger.clear();
     if (!(options === null || options === void 0 ? void 0 : options.disableConsoleLogging)) {
-        var formats = [winston_1.default.format.simple()];
+        var formats = [addRequestContextFormat(), winston_1.default.format.simple()];
         if (!(options === null || options === void 0 ? void 0 : options.disableConsoleColors)) {
             formats.push(winston_1.default.format.colorize());
         }
@@ -211,7 +232,7 @@ function setupLogging(options) {
             colorize: false,
             compress: true,
             dirname: logDirectory,
-            format: winston_1.default.format.simple(),
+            format: winston_1.default.format.combine(addRequestContextFormat(), winston_1.default.format.simple()),
             // 30 days of retention
             maxFiles: 30,
             // 50MB max file size
@@ -246,4 +267,5 @@ function setupLogging(options) {
             finally { if (e_1) throw e_1.error; }
         }
     }
-}
+};
+exports.setupLogging = setupLogging;

package/dist/models/versionConfig.d.ts

@@ -8,6 +8,8 @@ export interface VersionConfigDocument extends mongoose.Document {
     warningMessage: string;
     requiredMessage: string;
     updateUrl?: string;
+    /** How often clients should poll for version updates, in minutes. Defaults to 1440 (24 hours). */
+    pollingIntervalMinutes: number;
     created?: Date;
     updated?: Date;
 }

package/dist/models/versionConfig.js

@@ -19,6 +19,12 @@ var versionConfigSchema = new mongoose_1.default.Schema({
         min: 0,
         type: Number,
     },
+    pollingIntervalMinutes: {
+        default: 1440,
+        description: "How often clients poll for version updates, in minutes (default: 1440 = 24 hours)",
+        min: 1,
+        type: Number,
+    },
     requiredMessage: {
         default: "This version is no longer supported. Please update to continue.",
         description: "Message shown on the blocking screen",
@@ -62,5 +68,7 @@ versionConfigSchema.add({
 });
 versionConfigSchema.index({ _singleton: 1 }, { unique: true });
 versionConfigSchema.plugin(plugins_1.createdUpdatedPlugin);
+versionConfigSchema.plugin(plugins_1.isDeletedPlugin);
 versionConfigSchema.plugin(plugins_1.findOneOrNone);
+versionConfigSchema.plugin(plugins_1.findExactlyOne);
 exports.VersionConfig = mongoose_1.default.model("VersionConfig", versionConfigSchema);

package/dist/notifiers/googleChatNotifier.js

@@ -108,17 +108,16 @@ var sendToGoogleChat = function (messageText_1) {
         args_1[_i - 1] = arguments[_i];
     }
     return __awaiter(void 0, __spreadArray([messageText_1], __read(args_1), false), void 0, function (messageText, _a) {
-        var chatWebhooksString, msg, chatWebhooks, chatChannel, chatWebhookUrl, msg, formattedMessageText, error_1, errorObj;
-        var _b, _c, _d;
-        var _e = _a === void 0 ? {} : _a, channel = _e.channel, _f = _e.shouldThrow, shouldThrow = _f === void 0 ? false : _f, env = _e.env;
-        return __generator(this, function (_g) {
-            switch (_g.label) {
+        var chatWebhooksString, msg, chatWebhooks, chatChannel, chatWebhookUrl, msg, formattedMessageText, error_1, message;
+        var _b;
+        var _c = _a === void 0 ? {} : _a, channel = _c.channel, _d = _c.shouldThrow, shouldThrow = _d === void 0 ? false : _d, env = _c.env;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
                 case 0:
                     chatWebhooksString = process.env.GOOGLE_CHAT_WEBHOOKS;
                     if (!chatWebhooksString) {
                         msg = "GOOGLE_CHAT_WEBHOOKS not set. Google Chat message not sent";
-                        Sentry.captureException(new Error(msg));
-                        logger_1.logger.error(msg);
+                        Sentry.captureException(new errors_1.APIError({ status: 500, title: msg }));
                         return [2 /*return*/];
                     }
                     chatWebhooks = JSON.parse(chatWebhooksString !== null && chatWebhooksString !== void 0 ? chatWebhooksString : "{}");
@@ -126,30 +125,29 @@ var sendToGoogleChat = function (messageText_1) {
                     chatWebhookUrl = (_b = chatWebhooks[chatChannel]) !== null && _b !== void 0 ? _b : chatWebhooks.default;
                     if (!chatWebhookUrl) {
                         msg = "No webhook url set in env for ".concat(chatChannel, ". Google Chat message not sent");
-                        Sentry.captureException(new Error(msg));
-                        logger_1.logger.error(msg);
+                        Sentry.captureException(new errors_1.APIError({ status: 500, title: msg }));
                         return [2 /*return*/];
                     }
                     formattedMessageText = messageText;
                     if (env) {
                         formattedMessageText = "[".concat(env.toUpperCase(), "] ").concat(messageText);
                     }
-                    _g.label = 1;
+                    _e.label = 1;
                 case 1:
-                    _g.trys.push([1, 3, , 4]);
+                    _e.trys.push([1, 3, , 4]);
                     return [4 /*yield*/, axios_1.default.post(chatWebhookUrl, { text: formattedMessageText })];
                 case 2:
-                    _g.sent();
+                    _e.sent();
                     return [3 /*break*/, 4];
                 case 3:
-                    error_1 = _g.sent();
-                    errorObj = error_1;
-                    logger_1.logger.error("Error posting to Google Chat: ".concat((_c = errorObj.text) !== null && _c !== void 0 ? _c : errorObj.message));
+                    error_1 = _e.sent();
+                    message = (0, errors_1.errorMessage)(error_1);
+                    logger_1.logger.error("Error posting to Google Chat: ".concat(message));
                     Sentry.captureException(error_1);
                     if (shouldThrow) {
                         throw new errors_1.APIError({
                             status: 500,
-                            title: "Error posting to Google Chat: ".concat((_d = errorObj.text) !== null && _d !== void 0 ? _d : errorObj.message),
+                            title: "Error posting to Google Chat: ".concat(message),
                         });
                     }
                     return [3 /*break*/, 4];

package/dist/notifiers/googleChatNotifier.test.js

@@ -99,6 +99,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));

package/dist/notifiers/slackNotifier.js

@@ -112,11 +112,11 @@ var sendToSlack = function (text_1) {
         args_1[_i - 1] = arguments[_i];
     }
     return __awaiter(void 0, __spreadArray([text_1], __read(args_1), false), void 0, function (text, _a) {
-        var slackWebhookUrl, slackWebhooksString, slackWebhooks, channel, formattedText, error_1, errorObj;
-        var _b, _c, _d;
-        var _e = _a === void 0 ? {} : _a, slackChannel = _e.slackChannel, _f = _e.shouldThrow, shouldThrow = _f === void 0 ? false : _f, env = _e.env, url = _e.url;
-        return __generator(this, function (_g) {
-            switch (_g.label) {
+        var slackWebhookUrl, slackWebhooksString, slackWebhooks, channel, formattedText, error_1, message;
+        var _b;
+        var _c = _a === void 0 ? {} : _a, slackChannel = _c.slackChannel, _d = _c.shouldThrow, shouldThrow = _d === void 0 ? false : _d, env = _c.env, url = _c.url;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
                 case 0:
                     slackWebhookUrl = url;
                     if (!slackWebhookUrl) {
@@ -130,8 +130,10 @@ var sendToSlack = function (text_1) {
                         channel = slackChannel !== null && slackChannel !== void 0 ? slackChannel : "default";
                         slackWebhookUrl = (_b = slackWebhooks[channel]) !== null && _b !== void 0 ? _b : slackWebhooks.default;
                         if (!slackWebhookUrl) {
-                            Sentry.captureException(new Error("No webhook url set in env for ".concat(channel, ". Slack message not sent")));
-                            logger_1.logger.debug("No webhook url set in env for ".concat(channel, "."));
+                            Sentry.captureException(new errors_1.APIError({
+                                status: 500,
+                                title: "No webhook url set in env for ".concat(channel, ". Slack message not sent"),
+                            }));
                             return [2 /*return*/];
                         }
                     }
@@ -139,24 +141,24 @@ var sendToSlack = function (text_1) {
                     if (env) {
                         formattedText = "[".concat(env.toUpperCase(), "] ").concat(text);
                     }
-                    _g.label = 1;
+                    _e.label = 1;
                 case 1:
-                    _g.trys.push([1, 3, , 4]);
+                    _e.trys.push([1, 3, , 4]);
                     return [4 /*yield*/, axios_1.default.post(slackWebhookUrl, {
                             text: formattedText,
                         })];
                 case 2:
-                    _g.sent();
+                    _e.sent();
                     return [3 /*break*/, 4];
                 case 3:
-                    error_1 = _g.sent();
-                    errorObj = error_1;
-                    logger_1.logger.error("Error posting to slack: ".concat((_c = errorObj.text) !== null && _c !== void 0 ? _c : errorObj.message));
+                    error_1 = _e.sent();
+                    message = (0, errors_1.errorMessage)(error_1);
+                    logger_1.logger.error("Error posting to slack: ".concat(message));
                     Sentry.captureException(error_1);
                     if (shouldThrow) {
                         throw new errors_1.APIError({
                             status: 500,
-                            title: "Error posting to slack: ".concat((_d = errorObj.text) !== null && _d !== void 0 ? _d : errorObj.message),
+                            title: "Error posting to slack: ".concat(message),
                         });
                     }
                     return [3 /*break*/, 4];

package/dist/notifiers/slackNotifier.test.js

@@ -102,6 +102,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var bun_test_1 = require("bun:test");
 var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));
+var errors_1 = require("../errors");
 var slackNotifier_1 = require("./slackNotifier");
 (0, bun_test_1.describe)("sendToSlack", function () {
     var mockAxiosPost;
@@ -213,8 +214,44 @@ var slackNotifier_1 = require("./slackNotifier");
             }
         });
     }); });
+    (0, bun_test_1.it)("reports to Sentry and returns early when channel has no webhook and no default", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var captured;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    process.env.SLACK_WEBHOOKS = JSON.stringify({ ops: "https://slack.example/ops" });
+                    return [4 /*yield*/, (0, slackNotifier_1.sendToSlack)("orphan message", { slackChannel: "alerts" })];
+                case 1:
+                    _a.sent();
+                    (0, bun_test_1.expect)(mockAxiosPost.mock.calls.length).toBe(0);
+                    (0, bun_test_1.expect)(Sentry.captureException.mock.calls.length).toBe(1);
+                    captured = Sentry.captureException.mock
+                        .calls[0][0];
+                    (0, bun_test_1.expect)(captured).toBeInstanceOf(errors_1.APIError);
+                    (0, bun_test_1.expect)(captured.title).toContain("alerts");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("posts directly using the url parameter without env lookup", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, url, payload;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    mockAxiosPost.mockResolvedValue({ status: 200 });
+                    return [4 /*yield*/, (0, slackNotifier_1.sendToSlack)("direct msg", { url: "https://direct.example/hook" })];
+                case 1:
+                    _b.sent();
+                    (0, bun_test_1.expect)(mockAxiosPost.mock.calls.length).toBe(1);
+                    _a = __read(mockAxiosPost.mock.calls[0], 2), url = _a[0], payload = _a[1];
+                    (0, bun_test_1.expect)(url).toBe("https://direct.example/hook");
+                    (0, bun_test_1.expect)(payload).toEqual({ text: "direct msg" });
+                    return [2 /*return*/];
+            }
+        });
+    }); });
     (0, bun_test_1.it)("captures error and throws APIError when shouldThrow=true", function () { return __awaiter(void 0, void 0, void 0, function () {
-        var error_1;
+        var error_1, apiError;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -231,8 +268,9 @@ var slackNotifier_1 = require("./slackNotifier");
                     throw new Error("Expected sendToSlack to throw APIError");
                 case 3:
                     error_1 = _a.sent();
-                    (0, bun_test_1.expect)(error_1.name).toBe("APIError");
-                    (0, bun_test_1.expect)(error_1.title).toMatch(/Error posting to slack/i);
+                    apiError = error_1;
+                    (0, bun_test_1.expect)(apiError.name).toBe("APIError");
+                    (0, bun_test_1.expect)(apiError.title).toMatch(/Error posting to slack/i);
                     return [3 /*break*/, 4];
                 case 4:
                     (0, bun_test_1.expect)(mockAxiosPost.mock.calls.length).toBe(1);

package/dist/notifiers/zoomNotifier.js

@@ -103,7 +103,7 @@ var logger_1 = require("../logger");
  * Uses Zoom's rich message format (format=full) with structured header and body.
  */
 var sendToZoom = function (_a, _b) { return __awaiter(void 0, [_a, _b], void 0, function (_c, _d) {
-    var zoomWebhooksString, msg, zoomWebhooks, zoomChannel, zoomWebhookUrl, msg, zoomToken, msg, messageBody, error_1, errorMessage;
+    var zoomWebhooksString, msg, zoomWebhooks, zoomChannel, zoomWebhookUrl, msg, zoomToken, msg, messageBody, error_1, message;
     var _e, _f, _g, _h, _j, _k;
     var header = _c.header, body = _c.body, subheader = _c.subheader;
     var channel = _d.channel, _l = _d.shouldThrow, shouldThrow = _l === void 0 ? false : _l, env = _d.env;
@@ -113,8 +113,7 @@ var sendToZoom = function (_a, _b) { return __awaiter(void 0, [_a, _b], void 0,
                 zoomWebhooksString = process.env.ZOOM_CHAT_WEBHOOKS;
                 if (!zoomWebhooksString) {
                     msg = "ZOOM_CHAT_WEBHOOKS not set. Zoom message not sent";
-                    Sentry.captureException(new Error(msg));
-                    logger_1.logger.error(msg);
+                    Sentry.captureException(new errors_1.APIError({ status: 500, title: msg }));
                     return [2 /*return*/];
                 }
                 zoomWebhooks = JSON.parse(zoomWebhooksString !== null && zoomWebhooksString !== void 0 ? zoomWebhooksString : "{}");
@@ -122,15 +121,13 @@ var sendToZoom = function (_a, _b) { return __awaiter(void 0, [_a, _b], void 0,
                 zoomWebhookUrl = (_f = (_e = zoomWebhooks[zoomChannel]) === null || _e === void 0 ? void 0 : _e.channel) !== null && _f !== void 0 ? _f : (_g = zoomWebhooks.default) === null || _g === void 0 ? void 0 : _g.channel;
                 if (!zoomWebhookUrl) {
                     msg = "No webhook url set in env for ".concat(zoomChannel, ". Zoom message not sent");
-                    Sentry.captureException(new Error(msg));
-                    logger_1.logger.error(msg);
+                    Sentry.captureException(new errors_1.APIError({ status: 500, title: msg }));
                     return [2 /*return*/];
                 }
                 zoomToken = (_j = (_h = zoomWebhooks[zoomChannel]) === null || _h === void 0 ? void 0 : _h.verificationToken) !== null && _j !== void 0 ? _j : (_k = zoomWebhooks.default) === null || _k === void 0 ? void 0 : _k.verificationToken;
                 if (!zoomToken) {
                     msg = "No verification token set in env for ".concat(zoomChannel, ". Zoom message not sent");
-                    Sentry.captureException(new Error(msg));
-                    logger_1.logger.error(msg);
+                    Sentry.captureException(new errors_1.APIError({ status: 500, title: msg }));
                     return [2 /*return*/];
                 }
                 messageBody = {
@@ -163,13 +160,13 @@ var sendToZoom = function (_a, _b) { return __awaiter(void 0, [_a, _b], void 0,
                 return [3 /*break*/, 4];
             case 3:
                 error_1 = _m.sent();
-                errorMessage = error_1 instanceof Error ? error_1.message : String(error_1);
-                logger_1.logger.error("Error posting to Zoom: ".concat(errorMessage));
+                message = (0, errors_1.errorMessage)(error_1);
+                logger_1.logger.error("Error posting to Zoom: ".concat(message));
                 Sentry.captureException(error_1);
                 if (shouldThrow) {
                     throw new errors_1.APIError({
                         status: 500,
-                        title: "Error posting to Zoom: ".concat(errorMessage),
+                        title: "Error posting to Zoom: ".concat(message),
                     });
                 }
                 return [3 /*break*/, 4];

package/dist/notifiers/zoomNotifier.test.js

@@ -99,6 +99,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var Sentry = __importStar(require("@sentry/bun"));
 var axios_1 = __importDefault(require("axios"));

package/dist/openApi.d.ts

@@ -58,4 +58,4 @@ export declare function listOpenApiMiddleware<T>(model: Model<T>, options: Parti
 export declare function createOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
 export declare function patchOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
 export declare function deleteOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
-export declare function readOpenApiMiddleware<T>(options: Partial<ModelRouterOptions<T>>, properties: any, required: string[], queryParameters: any): any;
+export declare function readOpenApiMiddleware<T>(options: Partial<ModelRouterOptions<T>>, properties: Record<string, unknown>, required: string[], queryParameters: Array<Record<string, unknown>>): express.RequestHandler;

package/dist/openApi.test.js

@@ -66,6 +66,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var supertest_1 = __importDefault(require("supertest"));
 var api_1 = require("./api");

package/dist/openApiBuilder.d.ts

@@ -1,3 +1,35 @@
+/**
+ * OpenAPI Middleware Builder
+ *
+ * This module provides a fluent builder pattern for constructing OpenAPI middleware
+ * for Express routes that don't directly map to Mongoose models. It allows you to
+ * define custom API documentation with full control over request/response schemas.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import {createOpenApiBuilder} from "./openApiBuilder";
+ *
+ * // Create middleware with custom documentation
+ * const middleware = createOpenApiBuilder(options)
+ *   .withTags(["users"])
+ *   .withSummary("Get user statistics")
+ *   .withDescription("Returns aggregated statistics for the current user")
+ *   .withQueryParameter("period", {type: "string"}, {
+ *     description: "Time period for statistics",
+ *     required: false,
+ *   })
+ *   .withResponse<{count: number; average: number}>(200, {
+ *     count: {type: "number", description: "Total count"},
+ *     average: {type: "number", description: "Average value"},
+ *   })
+ *   .build();
+ *
+ * router.get("/stats", middleware, statsHandler);
+ * ```
+ */
+import type express from "express";
 import type { ModelRouterOptions } from "./api";
 /**
  * Defines a property within an OpenAPI schema.
@@ -68,7 +100,7 @@ export interface OpenApiSchemaProperty {
  * };
  * ```
  */
-export type OpenApiSchema = {
+export interface OpenApiSchema {
     /** The JSON Schema type (typically "object" or "array") */
     type: string;
     /** Property definitions for object types */
@@ -79,7 +111,8 @@ export type OpenApiSchema = {
     items?: OpenApiSchemaProperty;
     /** Schema for additional properties or boolean to allow/disallow them */
     additionalProperties?: OpenApiSchemaProperty | boolean;
-};
+    [key: string]: unknown;
+}
 /**
  * Defines a parameter in an OpenAPI operation.
  *
@@ -159,7 +192,7 @@ export interface OpenApiResponse {
  */
 export interface OpenApiBuildResult {
     /** The OpenAPI documentation middleware */
-    middleware: any;
+    middleware: express.RequestHandler;
     /** Request body schema if defined */
     bodySchema?: Record<string, OpenApiSchemaProperty>;
     /** Query parameter schemas if defined */
@@ -275,7 +308,7 @@ export declare class OpenApiMiddlewareBuilder {
      * });
      * ```
      */
-    withRequestBody<T extends Record<string, any>>(schema: {
+    withRequestBody<T extends Record<string, unknown>>(schema: {
         [K in keyof T]: OpenApiSchemaProperty;
     }, options?: {
         required?: boolean;
@@ -306,7 +339,7 @@ export declare class OpenApiMiddlewareBuilder {
      * builder.withResponse(204, "No content");
      * ```
      */
-    withResponse<T extends Record<string, any>>(statusCode: number, schema: {
+    withResponse<T extends Record<string, unknown>>(statusCode: number, schema: {
         [K in keyof T]: OpenApiSchemaProperty;
     } | string, options?: {
         description?: string;
@@ -334,7 +367,7 @@ export declare class OpenApiMiddlewareBuilder {
      * }, {description: "List of users"});
      * ```
      */
-    withArrayResponse<T extends Record<string, any>>(statusCode: number, itemSchema: {
+    withArrayResponse<T extends Record<string, unknown>>(statusCode: number, itemSchema: {
         [K in keyof T]: OpenApiSchemaProperty;
     }, options?: {
         description?: string;

package/dist/openApiBuilder.js

@@ -31,37 +31,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createOpenApiBuilder = exports.OpenApiMiddlewareBuilder = void 0;
-/**
- * OpenAPI Middleware Builder
- *
- * This module provides a fluent builder pattern for constructing OpenAPI middleware
- * for Express routes that don't directly map to Mongoose models. It allows you to
- * define custom API documentation with full control over request/response schemas.
- *
- * @packageDocumentation
- *
- * @example
- * ```typescript
- * import {createOpenApiBuilder} from "./openApiBuilder";
- *
- * // Create middleware with custom documentation
- * const middleware = createOpenApiBuilder(options)
- *   .withTags(["users"])
- *   .withSummary("Get user statistics")
- *   .withDescription("Returns aggregated statistics for the current user")
- *   .withQueryParameter("period", {type: "string"}, {
- *     description: "Time period for statistics",
- *     required: false,
- *   })
- *   .withResponse<{count: number; average: number}>(200, {
- *     count: {type: "number", description: "Total count"},
- *     average: {type: "number", description: "Average value"},
- *   })
- *   .build();
- *
- * router.get("/stats", middleware, statsHandler);
- * ```
- */
 var merge_1 = __importDefault(require("lodash/merge"));
 var logger_1 = require("./logger");
 var openApi_1 = require("./openApi");
@@ -469,6 +438,7 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * router.get("/users/:id", middleware, getUserHandler);
      * ```
      */
+    // biome-ignore lint/suspicious/noExplicitAny: returns either a single RequestHandler or an array depending on validation config — callers spread or invoke
     OpenApiMiddlewareBuilder.prototype.build = function () {
         var _c, _d, _e, _f, _g;
         var noop = function (_a, _b, next) { return next(); };

package/dist/openApiBuilder.test.js

@@ -50,6 +50,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var supertest_1 = __importDefault(require("supertest"));
 var api_1 = require("./api");

package/dist/openApiValidator.js

@@ -191,6 +191,7 @@ var getAjvInstance = function () {
             useDefaults: true,
             validateSchema: false,
         });
+        // biome-ignore lint/suspicious/noExplicitAny: ajv-formats has a known type compat issue with AJV instances
         (0, ajv_formats_1.default)(instance);
         ajvCache.set(key, instance);
     }