@terreno/api 0.0.18 → 0.2.0

package/dist/openApiValidator.test.js

@@ -0,0 +1,346 @@
+"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 __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var api_1 = require("./api");
+var auth_1 = require("./auth");
+var openApiValidator_1 = require("./openApiValidator");
+var permissions_1 = require("./permissions");
+var tests_1 = require("./tests");
+// RequiredModel has a clean schema that AJV can compile (no non-standard types).
+// It has: name (String, required), about (String, optional)
+var requiredRouterOptions = {
+    permissions: {
+        create: [permissions_1.Permissions.IsAuthenticated],
+        delete: [permissions_1.Permissions.IsAdmin],
+        list: [permissions_1.Permissions.IsAuthenticated],
+        read: [permissions_1.Permissions.IsAuthenticated],
+        update: [permissions_1.Permissions.IsAuthenticated],
+    },
+    queryFields: ["name"],
+    sort: "-name",
+};
+var setupFreshApp = function () { return __awaiter(void 0, void 0, void 0, function () {
+    var freshApp;
+    return __generator(this, function (_a) {
+        freshApp = (0, tests_1.getBaseServer)();
+        (0, auth_1.setupAuth)(freshApp, tests_1.UserModel);
+        (0, auth_1.addAuthRoutes)(freshApp, tests_1.UserModel);
+        return [2 /*return*/, freshApp];
+    });
+}); };
+(0, bun_test_1.describe)("openApiValidator", function () {
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    (0, openApiValidator_1.resetOpenApiValidatorConfig)();
+                    return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, tests_1.RequiredModel.deleteMany({})];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () {
+        (0, openApiValidator_1.resetOpenApiValidatorConfig)();
+    });
+    (0, bun_test_1.describe)("isConfigured flag", function () {
+        (0, bun_test_1.it)("is false by default", function () {
+            (0, bun_test_1.expect)((0, openApiValidator_1.isOpenApiValidatorConfigured)()).toBe(false);
+        });
+        (0, bun_test_1.it)("becomes true after configureOpenApiValidator()", function () {
+            (0, openApiValidator_1.configureOpenApiValidator)();
+            (0, bun_test_1.expect)((0, openApiValidator_1.isOpenApiValidatorConfigured)()).toBe(true);
+        });
+        (0, bun_test_1.it)("resets to false after resetOpenApiValidatorConfig()", function () {
+            (0, openApiValidator_1.configureOpenApiValidator)();
+            (0, bun_test_1.expect)((0, openApiValidator_1.isOpenApiValidatorConfigured)()).toBe(true);
+            (0, openApiValidator_1.resetOpenApiValidatorConfig)();
+            (0, bun_test_1.expect)((0, openApiValidator_1.isOpenApiValidatorConfigured)()).toBe(false);
+        });
+    });
+    (0, bun_test_1.describe)("no-op when not configured", function () {
+        (0, bun_test_1.it)("does not strip or validate when not configured", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var freshApp, admin, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, setupFreshApp()];
+                    case 1:
+                        freshApp = _a.sent();
+                        freshApp.use("/required", (0, api_1.modelRouter)(tests_1.RequiredModel, requiredRouterOptions));
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(freshApp, "admin")];
+                    case 2:
+                        admin = _a.sent();
+                        return [4 /*yield*/, admin.post("/required").send({ name: "Apple" }).expect(201)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data.name).toBe("Apple");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("active after configuration", function () {
+        (0, bun_test_1.it)("strips extra properties when removeAdditional is true", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var freshApp, admin, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        (0, openApiValidator_1.configureOpenApiValidator)({ removeAdditional: true });
+                        return [4 /*yield*/, setupFreshApp()];
+                    case 1:
+                        freshApp = _a.sent();
+                        freshApp.use("/required", (0, api_1.modelRouter)(tests_1.RequiredModel, requiredRouterOptions));
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(freshApp, "admin")];
+                    case 2:
+                        admin = _a.sent();
+                        return [4 /*yield*/, admin
+                                .post("/required")
+                                .send({ fakeField: "this should be stripped", name: "Apple" })
+                                .expect(201)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data.name).toBe("Apple");
+                        (0, bun_test_1.expect)(res.body.data.fakeField).toBeUndefined();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("rejects missing required fields", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var freshApp, admin, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        (0, openApiValidator_1.configureOpenApiValidator)();
+                        return [4 /*yield*/, setupFreshApp()];
+                    case 1:
+                        freshApp = _a.sent();
+                        freshApp.use("/required", (0, api_1.modelRouter)(tests_1.RequiredModel, requiredRouterOptions));
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(freshApp, "admin")];
+                    case 2:
+                        admin = _a.sent();
+                        return [4 /*yield*/, admin.post("/required").send({ about: "no name" }).expect(400)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.title).toBe("Request validation failed");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("onAdditionalPropertiesRemoved hook", function () {
+        (0, bun_test_1.it)("fires callback with removed property names", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var removedProps, freshApp, admin;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        removedProps = [];
+                        (0, openApiValidator_1.configureOpenApiValidator)({
+                            onAdditionalPropertiesRemoved: function (props) {
+                                removedProps.push.apply(removedProps, __spreadArray([], __read(props), false));
+                            },
+                            removeAdditional: true,
+                        });
+                        return [4 /*yield*/, setupFreshApp()];
+                    case 1:
+                        freshApp = _a.sent();
+                        freshApp.use("/required", (0, api_1.modelRouter)(tests_1.RequiredModel, requiredRouterOptions));
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(freshApp, "admin")];
+                    case 2:
+                        admin = _a.sent();
+                        return [4 /*yield*/, admin
+                                .post("/required")
+                                .send({ extraA: "stripped", extraB: "also stripped", name: "Apple" })
+                                .expect(201)];
+                    case 3:
+                        _a.sent();
+                        (0, bun_test_1.expect)(removedProps).toContain("extraA");
+                        (0, bun_test_1.expect)(removedProps).toContain("extraB");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("per-route validation: false override", function () {
+        (0, bun_test_1.it)("skips validation when validation is false", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var freshApp, admin, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        (0, openApiValidator_1.configureOpenApiValidator)({ removeAdditional: true });
+                        return [4 /*yield*/, setupFreshApp()];
+                    case 1:
+                        freshApp = _a.sent();
+                        freshApp.use("/required", (0, api_1.modelRouter)(tests_1.RequiredModel, __assign(__assign({}, requiredRouterOptions), { validation: false })));
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(freshApp, "admin")];
+                    case 2:
+                        admin = _a.sent();
+                        return [4 /*yield*/, admin
+                                .post("/required")
+                                .send({ fakeField: "not stripped", name: "Apple" })
+                                .expect(201)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data.name).toBe("Apple");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("sanitization of non-standard mongoose-to-swagger types", function () {
+        (0, bun_test_1.it)("validates models with ObjectId and DateOnly fields after sanitization", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var freshApp, admin, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        (0, openApiValidator_1.configureOpenApiValidator)({ removeAdditional: true });
+                        return [4 /*yield*/, setupFreshApp()];
+                    case 1:
+                        freshApp = _a.sent();
+                        freshApp.use("/food", (0, api_1.modelRouter)(tests_1.FoodModel, {
+                            permissions: {
+                                create: [permissions_1.Permissions.IsAuthenticated],
+                                delete: [permissions_1.Permissions.IsAdmin],
+                                list: [permissions_1.Permissions.IsAuthenticated],
+                                read: [permissions_1.Permissions.IsAuthenticated],
+                                update: [permissions_1.Permissions.IsAuthenticated],
+                            },
+                            queryFields: ["name", "calories", "hidden"],
+                            sort: "-created",
+                        }));
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(freshApp, "admin")];
+                    case 2:
+                        admin = _a.sent();
+                        return [4 /*yield*/, admin
+                                .post("/food")
+                                .send({ calories: 100, likesIds: [], name: "Apple", source: { name: "Test" } })
+                                .expect(201)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data.name).toBe("Apple");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("buildQuerySchemaFromFields", function () {
+        (0, bun_test_1.it)("always includes limit, page, and sort", function () {
+            var schema = (0, openApiValidator_1.buildQuerySchemaFromFields)(tests_1.FoodModel, []);
+            (0, bun_test_1.expect)(schema.limit).toBeDefined();
+            (0, bun_test_1.expect)(schema.page).toBeDefined();
+            (0, bun_test_1.expect)(schema.sort).toBeDefined();
+        });
+        (0, bun_test_1.it)("includes queryFields from model schema", function () {
+            var schema = (0, openApiValidator_1.buildQuerySchemaFromFields)(tests_1.FoodModel, ["name", "calories"]);
+            (0, bun_test_1.expect)(schema.name).toBeDefined();
+            (0, bun_test_1.expect)(schema.calories).toBeDefined();
+            (0, bun_test_1.expect)(schema.hidden).toBeUndefined();
+        });
+        (0, bun_test_1.it)("marks query fields as not required", function () {
+            var schema = (0, openApiValidator_1.buildQuerySchemaFromFields)(tests_1.FoodModel, ["name"]);
+            (0, bun_test_1.expect)(schema.name.required).toBe(false);
+        });
+    });
+    (0, bun_test_1.describe)("validateRequestBody middleware", function () {
+        (0, bun_test_1.it)("is a no-op when not configured", function () {
+            (0, openApiValidator_1.resetOpenApiValidatorConfig)();
+            var middleware = (0, openApiValidator_1.validateRequestBody)({
+                name: { required: true, type: "string" },
+            });
+            var nextCalled = false;
+            var req = { body: {} };
+            var res = {};
+            var next = function () {
+                nextCalled = true;
+            };
+            middleware(req, res, next);
+            (0, bun_test_1.expect)(nextCalled).toBe(true);
+        });
+        (0, bun_test_1.it)("validates when configured", function () {
+            (0, openApiValidator_1.configureOpenApiValidator)();
+            var middleware = (0, openApiValidator_1.validateRequestBody)({
+                name: { required: true, type: "string" },
+            });
+            var req = { body: {}, method: "POST", path: "/test" };
+            var res = {};
+            (0, bun_test_1.expect)(function () {
+                middleware(req, res, function () { });
+            }).toThrow();
+        });
+    });
+});

package/dist/plugins.test.js

@@ -64,9 +64,9 @@ var permissions_1 = require("./permissions");
 var plugins_1 = require("./plugins");
 var tests_1 = require("./tests");
 var stuffSchema = new mongoose_1.Schema({
-    date: plugins_1.DateOnly,
-    name: String,
-    ownerId: String,
+    date: { description: "The date associated with this item", type: plugins_1.DateOnly },
+    name: { description: "The name of the item", type: String },
+    ownerId: { description: "The user who owns this item", type: String },
 });
 stuffSchema.plugin(plugins_1.isDeletedPlugin);
 stuffSchema.plugin(plugins_1.findOneOrNone);

package/dist/terrenoApp.d.ts

@@ -0,0 +1,189 @@
+import * as Sentry from "@sentry/bun";
+import express from "express";
+import type { ModelRouterRegistration } from "./api";
+import { type UserModel as UserMongooseModel } from "./auth";
+import { type AuthOptions } from "./expressServer";
+import { type GitHubAuthOptions } from "./githubAuth";
+import { type LoggingOptions } from "./logger";
+import type { TerrenoPlugin } from "./terrenoPlugin";
+type CorsOrigin = string | boolean | RegExp | Array<boolean | string | RegExp> | ((requestOrigin: string | undefined, callback: (err: Error | null, origin?: boolean | string | RegExp | Array<boolean | string | RegExp>) => void) => void);
+/**
+ * Configuration options for TerrenoApp.
+ */
+export interface TerrenoAppOptions {
+    /** Mongoose User model with passport-local-mongoose plugin */
+    userModel: UserMongooseModel;
+    /** CORS origin configuration (default: "*") */
+    corsOrigin?: CorsOrigin;
+    /** Logging configuration options */
+    loggingOptions?: LoggingOptions;
+    /** Authentication configuration options */
+    authOptions?: AuthOptions;
+    /** GitHub OAuth configuration (enables GitHub authentication if provided) */
+    githubAuth?: GitHubAuthOptions;
+    /** Skip calling app.listen() in start() method (useful for testing) */
+    skipListen?: boolean;
+    /** Sentry configuration options */
+    sentryOptions?: Sentry.BunOptions;
+    /** Maximum number of array items in query parameters (default: 200) */
+    arrayLimit?: number;
+    /** Whether to log all incoming requests (default: true) */
+    logRequests?: boolean;
+}
+/**
+ * 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
+ */
+export declare class TerrenoApp {
+    private options;
+    private registrations;
+    private middlewareFns;
+    /**
+     * Create a new TerrenoApp builder.
+     *
+     * @param options - Application configuration options including user model and auth settings
+     */
+    constructor(options: TerrenoAppOptions);
+    /**
+     * 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);
+     * ```
+     */
+    register(registration: ModelRouterRegistration | TerrenoPlugin): 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();
+     * });
+     * ```
+     */
+    addMiddleware(fn: express.RequestHandler | ((app: express.Application) => void)): 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);
+     * ```
+     */
+    build(): express.Application;
+    /**
+     * 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();
+     * ```
+     */
+    start(): express.Application;
+    private isModelRouterRegistration;
+}
+export {};