@terreno/api 0.0.18 → 0.2.0

package/dist/terrenoApp.js

@@ -0,0 +1,352 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerrenoApp = void 0;
+var Sentry = __importStar(require("@sentry/bun"));
+var openapi_1 = __importDefault(require("@wesleytodd/openapi"));
+var cors_1 = __importDefault(require("cors"));
+var express_1 = __importDefault(require("express"));
+var qs_1 = __importDefault(require("qs"));
+var auth_1 = require("./auth");
+var errors_1 = require("./errors");
+var expressServer_1 = require("./expressServer");
+var githubAuth_1 = require("./githubAuth");
+var logger_1 = require("./logger");
+var openApiEtag_1 = require("./openApiEtag");
+/**
+ * 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.
+ *
+ * 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
+ * 10. GitHub OAuth routes (if enabled)
+ * 11. Registered model routers and plugins
+ * 12. Error handling middleware
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with model routers
+ * const todoRouter = modelRouter("/todos", Todo, {
+ *   permissions: { list: [Permissions.IsAuthenticated], ... },
+ * });
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(todoRouter)
+ *   .register(new HealthApp())
+ *   .start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom middleware
+ * const app = new TerrenoApp({
+ *   userModel: User,
+ *   corsOrigin: ["https://app.example.com"],
+ *   loggingOptions: { logRequests: true },
+ *   githubAuth: {
+ *     clientId: process.env.GITHUB_CLIENT_ID!,
+ *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     callbackURL: process.env.GITHUB_CALLBACK_URL!,
+ *   },
+ * })
+ *   .addMiddleware((req, res, next) => {
+ *     res.setHeader("X-Custom-Header", "value");
+ *     next();
+ *   })
+ *   .register(todoRouter)
+ *   .register(userRouter)
+ *   .start();
+ * ```
+ *
+ * @see setupServer for the callback-based alternative
+ * @see TerrenoPlugin for creating reusable plugins
+ * @see modelRouter for creating CRUD route registrations
+ */
+var TerrenoApp = /** @class */ (function () {
+    /**
+     * Create a new TerrenoApp builder.
+     *
+     * @param options - Application configuration options including user model and auth settings
+     */
+    function TerrenoApp(options) {
+        this.registrations = [];
+        this.middlewareFns = [];
+        this.options = options;
+    }
+    /**
+     * Register a model router or plugin with the application.
+     *
+     * Model routers are created with `modelRouter("/path", Model, options)` and
+     * provide CRUD endpoints. Plugins implement `TerrenoPlugin` interface and
+     * can register custom routes and middleware.
+     *
+     * Registrations are mounted in the order they are added.
+     *
+     * @param registration - A ModelRouterRegistration from modelRouter() or a TerrenoPlugin instance
+     * @returns This TerrenoApp instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const todoRouter = modelRouter("/todos", Todo, options);
+     * const healthPlugin = new HealthApp({ path: "/health" });
+     *
+     * app.register(todoRouter).register(healthPlugin);
+     * ```
+     */
+    TerrenoApp.prototype.register = function (registration) {
+        this.registrations.push(registration);
+        return this;
+    };
+    /**
+     * Add custom Express middleware to the application.
+     *
+     * Middleware is added BEFORE JSON body parsing and authentication setup,
+     * allowing you to modify incoming requests early in the middleware stack.
+     *
+     * @param fn - Express middleware function or a function that configures the app
+     * @returns This TerrenoApp instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * app.addMiddleware((req, res, next) => {
+     *   res.setHeader("X-Request-ID", req.id);
+     *   next();
+     * });
+     * ```
+     */
+    TerrenoApp.prototype.addMiddleware = function (fn) {
+        this.middlewareFns.push(fn);
+        return this;
+    };
+    /**
+     * Build the Express application without starting the server.
+     *
+     * Configures the complete middleware stack including:
+     * - CORS, JSON parsing, authentication, logging, Sentry, OpenAPI
+     * - All registered model routers and plugins
+     * - Error handling middleware
+     *
+     * Use this method when you need the Express app instance for testing
+     * or custom server setup. For normal use, call `start()` instead.
+     *
+     * @returns Configured Express application instance
+     *
+     * @example
+     * ```typescript
+     * const app = new TerrenoApp({ userModel: User })
+     *   .register(todoRouter)
+     *   .build();
+     *
+     * // Use app for testing with supertest
+     * await request(app).get("/todos").expect(200);
+     * ```
+     */
+    TerrenoApp.prototype.build = function () {
+        var e_1, _a, e_2, _b;
+        var _c;
+        (0, logger_1.setupLogging)(this.options.loggingOptions);
+        var app = (0, express_1.default)();
+        var options = this.options;
+        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((0, cors_1.default)({ origin: (_c = options.corsOrigin) !== null && _c !== void 0 ? _c : "*" }));
+        try {
+            // Apply custom middleware before JSON parsing
+            for (var _d = __values(this.middlewareFns), _e = _d.next(); !_e.done; _e = _d.next()) {
+                var fn = _e.value;
+                if (fn.length <= 3) {
+                    // express.RequestHandler (req, res, next)
+                    app.use(fn);
+                }
+                else {
+                    // Function that receives the app
+                    fn(app);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        app.use(express_1.default.json());
+        // Auth routes (login/signup/refresh_token) before JWT middleware
+        (0, auth_1.addAuthRoutes)(app, options.userModel, options.authOptions);
+        (0, auth_1.setupAuth)(app, options.userModel);
+        if (options.logRequests !== false) {
+            app.use(expressServer_1.logRequests);
+        }
+        // Store logging options on the response locals
+        app.use(function (_req, res, next) {
+            res.locals.loggingOptions = options.loggingOptions;
+            next();
+        });
+        // Sentry scopes
+        app.all("*", function (req, _res, next) {
+            var _a;
+            var transactionId = req.header("X-Transaction-ID");
+            var sessionId = req.header("X-Session-ID");
+            if (transactionId) {
+                Sentry.getCurrentScope().setTag("transaction_id", transactionId);
+            }
+            if (sessionId) {
+                Sentry.getCurrentScope().setTag("session_id", sessionId);
+            }
+            if ((_a = req.user) === null || _a === void 0 ? void 0 : _a._id) {
+                Sentry.getCurrentScope().setTag("user", req.user._id);
+            }
+            next();
+        });
+        // OpenAPI
+        app.use(openApiEtag_1.openApiEtagMiddleware);
+        var oapi = (0, openapi_1.default)({
+            info: {
+                description: "Generated docs from an Express api",
+                title: "Express Application",
+                version: "1.0.0",
+            },
+            openapi: "3.0.0",
+        });
+        app.use(oapi);
+        if (process.env.ENABLE_SWAGGER === "true") {
+            app.use("/swagger", oapi.swaggerui());
+        }
+        (0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions);
+        // GitHub OAuth
+        if (options.githubAuth) {
+            (0, githubAuth_1.setupGitHubAuth)(app, options.userModel, options.githubAuth);
+            (0, githubAuth_1.addGitHubAuthRoutes)(app, options.userModel, options.githubAuth, options.authOptions);
+        }
+        try {
+            // Mount registered model routers and plugins
+            for (var _f = __values(this.registrations), _g = _f.next(); !_g.done; _g = _f.next()) {
+                var registration = _g.value;
+                if (this.isModelRouterRegistration(registration)) {
+                    app.use(registration.path, registration.router);
+                }
+                else {
+                    registration.register(app);
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        // Inject openApi into model router options for registered routers
+        // The openApi middleware handles this via the oapi instance already mounted on the app
+        Sentry.setupExpressErrorHandler(app);
+        // Error middleware
+        app.use(errors_1.apiUnauthorizedMiddleware);
+        app.use(errors_1.apiErrorMiddleware);
+        app.use(function onError(err, _req, res, _next) {
+            logger_1.logger.error("Fallthrough error: ".concat(err).concat((err === null || err === void 0 ? void 0 : err.stack) ? "\n".concat(err.stack) : "", "}"));
+            Sentry.captureException(err);
+            res.statusCode = 500;
+            res.end("".concat(res.sentry, "\n"));
+        });
+        return app;
+    };
+    /**
+     * Build the Express application and start listening on the configured port.
+     *
+     * Calls `build()` to configure the application, then starts an HTTP server
+     * listening on the port specified by the `PORT` environment variable (default: 9000).
+     * If `skipListen` option is true, the app is built but the server is not started.
+     *
+     * @returns Configured Express application instance
+     *
+     * @throws Process exits with code 1 if the server fails to start
+     *
+     * @example
+     * ```typescript
+     * // Start server on port 3000
+     * process.env.PORT = "3000";
+     * const app = new TerrenoApp({ userModel: User })
+     *   .register(todoRouter)
+     *   .start();
+     * ```
+     */
+    TerrenoApp.prototype.start = function () {
+        var app = this.build();
+        if (!this.options.skipListen) {
+            var port_1 = process.env.PORT || "9000";
+            try {
+                app.listen(port_1, function () {
+                    logger_1.logger.info("Listening on port ".concat(port_1));
+                });
+            }
+            catch (error) {
+                logger_1.logger.error("Error trying to start HTTP server: ".concat(error, "\n").concat(error.stack));
+                process.exit(1);
+            }
+        }
+        return app;
+    };
+    TerrenoApp.prototype.isModelRouterRegistration = function (registration) {
+        return registration.__type === "modelRouter";
+    };
+    return TerrenoApp;
+}());
+exports.TerrenoApp = TerrenoApp;

package/dist/terrenoApp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/terrenoApp.test.js

@@ -0,0 +1,264 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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 __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+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 supertest_1 = __importDefault(require("supertest"));
+var api_1 = require("./api");
+var permissions_1 = require("./permissions");
+var terrenoApp_1 = require("./terrenoApp");
+var tests_1 = require("./tests");
+(0, bun_test_1.describe)("TerrenoApp", function () {
+    var originalEnv = process.env;
+    (0, bun_test_1.beforeEach)(function () {
+        process.env = __assign(__assign({}, originalEnv), { REFRESH_TOKEN_SECRET: "test-refresh-secret", SESSION_SECRET: "test-session-secret", TOKEN_EXPIRES_IN: "1h", TOKEN_ISSUER: "test-issuer", TOKEN_SECRET: "test-secret" });
+    });
+    (0, bun_test_1.afterEach)(function () {
+        process.env = originalEnv;
+    });
+    (0, bun_test_1.describe)("build", function () {
+        (0, bun_test_1.it)("returns an express application without listening", function () {
+            var app = new terrenoApp_1.TerrenoApp({
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            }).build();
+            (0, bun_test_1.expect)(app).toBeDefined();
+        });
+        (0, bun_test_1.it)("creates server with custom corsOrigin", function () {
+            var app = new terrenoApp_1.TerrenoApp({
+                corsOrigin: "https://example.com",
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            }).build();
+            (0, bun_test_1.expect)(app).toBeDefined();
+        });
+    });
+    (0, bun_test_1.describe)("start", function () {
+        (0, bun_test_1.it)("returns an express application with skipListen", function () {
+            var app = new terrenoApp_1.TerrenoApp({
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            }).start();
+            (0, bun_test_1.expect)(app).toBeDefined();
+        });
+    });
+    (0, bun_test_1.describe)("register with modelRouter", function () {
+        var admin;
+        (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                    case 1:
+                        _a = __read.apply(void 0, [_b.sent(), 1]), admin = _a[0];
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("mounts model router at the specified path", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var foodRegistration, app, agent, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        foodRegistration = (0, api_1.modelRouter)("/food", tests_1.FoodModel, {
+                            allowAnonymous: true,
+                            permissions: {
+                                create: [permissions_1.Permissions.IsAny],
+                                delete: [permissions_1.Permissions.IsAny],
+                                list: [permissions_1.Permissions.IsAny],
+                                read: [permissions_1.Permissions.IsAny],
+                                update: [permissions_1.Permissions.IsAny],
+                            },
+                            sort: "-created",
+                        });
+                        (0, bun_test_1.expect)(foodRegistration.__type).toBe("modelRouter");
+                        (0, bun_test_1.expect)(foodRegistration.path).toBe("/food");
+                        app = new terrenoApp_1.TerrenoApp({
+                            skipListen: true,
+                            userModel: tests_1.UserModel,
+                        })
+                            .register(foodRegistration)
+                            .build();
+                        return [4 /*yield*/, tests_1.FoodModel.create({
+                                calories: 100,
+                                name: "Apple",
+                                ownerId: admin._id,
+                                source: { name: "Nature" },
+                            })];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 2:
+                        agent = _a.sent();
+                        return [4 /*yield*/, agent.get("/food").expect(200)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data).toHaveLength(1);
+                        (0, bun_test_1.expect)(res.body.data[0].name).toBe("Apple");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("supports chaining multiple registrations", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var foodRegistration, app;
+            return __generator(this, function (_a) {
+                foodRegistration = (0, api_1.modelRouter)("/food", tests_1.FoodModel, {
+                    allowAnonymous: true,
+                    permissions: {
+                        create: [permissions_1.Permissions.IsAny],
+                        delete: [permissions_1.Permissions.IsAny],
+                        list: [permissions_1.Permissions.IsAny],
+                        read: [permissions_1.Permissions.IsAny],
+                        update: [permissions_1.Permissions.IsAny],
+                    },
+                });
+                app = new terrenoApp_1.TerrenoApp({
+                    skipListen: true,
+                    userModel: tests_1.UserModel,
+                })
+                    .register(foodRegistration)
+                    .build();
+                (0, bun_test_1.expect)(app).toBeDefined();
+                return [2 /*return*/];
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("register with plugin", function () {
+        (0, bun_test_1.it)("calls plugin.register with the express app", function () {
+            var registerFn = (0, bun_test_1.mock)(function () { });
+            var plugin = {
+                register: registerFn,
+            };
+            var app = new terrenoApp_1.TerrenoApp({
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            })
+                .register(plugin)
+                .build();
+            (0, bun_test_1.expect)(registerFn).toHaveBeenCalledTimes(1);
+            // Verify the plugin received the express app
+            var calledWith = registerFn.mock.calls[0][0];
+            (0, bun_test_1.expect)(calledWith).toBe(app);
+        });
+    });
+    (0, bun_test_1.describe)("addMiddleware", function () {
+        (0, bun_test_1.it)("runs request handler middleware", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var middlewareCalled, middleware, app;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        middlewareCalled = false;
+                        middleware = function (_req, _res, next) {
+                            middlewareCalled = true;
+                            next();
+                        };
+                        app = new terrenoApp_1.TerrenoApp({
+                            skipListen: true,
+                            userModel: tests_1.UserModel,
+                        })
+                            .addMiddleware(middleware)
+                            .build();
+                        return [4 /*yield*/, (0, supertest_1.default)(app).get("/nonexistent").expect(404)];
+                    case 1:
+                        _a.sent();
+                        (0, bun_test_1.expect)(middlewareCalled).toBe(true);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("modelRouter overload", function () {
+        (0, bun_test_1.it)("returns ModelRouterRegistration when path is provided", function () {
+            var result = (0, api_1.modelRouter)("/food", tests_1.FoodModel, {
+                permissions: {
+                    create: [permissions_1.Permissions.IsAny],
+                    delete: [permissions_1.Permissions.IsAny],
+                    list: [permissions_1.Permissions.IsAny],
+                    read: [permissions_1.Permissions.IsAny],
+                    update: [permissions_1.Permissions.IsAny],
+                },
+            });
+            (0, bun_test_1.expect)(result.__type).toBe("modelRouter");
+            (0, bun_test_1.expect)(result.path).toBe("/food");
+            (0, bun_test_1.expect)(result.router).toBeDefined();
+        });
+        (0, bun_test_1.it)("returns express.Router when no path is provided", function () {
+            var result = (0, api_1.modelRouter)(tests_1.FoodModel, {
+                permissions: {
+                    create: [permissions_1.Permissions.IsAny],
+                    delete: [permissions_1.Permissions.IsAny],
+                    list: [permissions_1.Permissions.IsAny],
+                    read: [permissions_1.Permissions.IsAny],
+                    update: [permissions_1.Permissions.IsAny],
+                },
+            });
+            // Should be a regular router (function), not a ModelRouterRegistration
+            (0, bun_test_1.expect)(typeof result).toBe("function");
+            (0, bun_test_1.expect)(result.__type).toBeUndefined();
+        });
+    });
+});

package/dist/terrenoPlugin.d.ts

@@ -0,0 +1,38 @@
+import type express from "express";
+/**
+ * Interface for plugins that can be registered with TerrenoApp.
+ *
+ * Implement this interface to create reusable plugins that encapsulate
+ * routes, middleware, or other Express application setup. Plugins are
+ * registered via `TerrenoApp.register()` and are mounted after core
+ * authentication and OpenAPI middleware.
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin implements TerrenoPlugin {
+ *   register(app: express.Application): void {
+ *     app.get("/my-route", (req, res) => {
+ *       res.json({ status: "ok" });
+ *     });
+ *   }
+ * }
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(new MyPlugin())
+ *   .start();
+ * ```
+ *
+ * @see TerrenoApp for the application builder that consumes plugins
+ * @see HealthApp for a built-in plugin example
+ */
+export interface TerrenoPlugin {
+    /**
+     * Register routes and middleware with the Express application.
+     *
+     * Called during `TerrenoApp.build()` after core middleware has been
+     * configured but before error handling middleware is added.
+     *
+     * @param app - The Express application instance to register with
+     */
+    register(app: express.Application): void;
+}

package/dist/terrenoPlugin.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });