@terreno/api 0.0.18 → 0.2.0

package/README.md

@@ -9,6 +9,14 @@ These APIs integrate with @terreno/rtk to create consistent types on the fronten
 and backend, and automatically generated React hooks to fetch, query, and modify
 model instances.
 
+## Features
+
+- **modelRouter** — Automatic CRUD endpoints for Mongoose models
+- **Authentication** — JWT with email/password and GitHub OAuth support
+- **Permissions** — Fine-grained access control (IsAuthenticated, IsOwner, IsAdmin, etc.)
+- **OpenAPI** — Automatic spec generation from models and routes
+- **Logging** — Winston-based logging with Google Cloud and Sentry support
+
 ## Getting started
 
 To install:
@@ -46,12 +54,25 @@ const eventSchema = new Schema({
 Assuming we have a model:
 
     const foodSchema = new Schema<Food>({
-      name: String,
-      hidden: {type: Boolean, default: false},
-      ownerId: {type: "ObjectId", ref: "User"},
+      name: {
+        description: "Name of the food item",
+        type: String,
+      },
+      hidden: {
+        description: "Whether the food is hidden from the list",
+        type: Boolean,
+        default: false,
+      },
+      ownerId: {
+        description: "The user who added this food",
+        type: "ObjectId",
+        ref: "User",
+      },
     });
     export const FoodModel = model("Food", foodSchema);
 
+**Important:** Every field must include a `description` property. This requirement ensures that the auto-generated OpenAPI specification and SDK have meaningful documentation for all fields.
+
 We can expose this model as an API like this:
 
     import express from "express";
@@ -99,6 +120,55 @@ Now we can perform operations on the Food model in a standard REST way. We've al
 
 You can create your own permissions functions. Check permissions.ts for some examples of how to write them.
 
+## Authentication
+
+@terreno/api includes built-in authentication with JWT and OAuth support.
+
+### Email/Password Authentication
+
+Built-in email/password authentication using `passport-local-mongoose`:
+
+```typescript
+import {setupServer} from "@terreno/api";
+import {User} from "./models/user";
+
+setupServer({
+  userModel: User,
+  addRoutes: (router) => {
+    // Your routes here
+  },
+});
+```
+
+This automatically adds:
+- `POST /auth/signup` — User registration
+- `POST /auth/login` — Authentication
+- `POST /auth/refresh_token` — Token refresh
+- `GET /auth/me` — Get current user
+- `PATCH /auth/me` — Update current user
+
+### GitHub OAuth
+
+Add GitHub OAuth login to your API:
+
+```typescript
+import {githubUserPlugin, setupServer} from "@terreno/api";
+
+// Add GitHub fields to user schema
+userSchema.plugin(githubUserPlugin);
+
+setupServer({
+  userModel: User,
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL!,
+  },
+});
+```
+
+**Learn more:** See the [GitHub OAuth how-to guide](../docs/how-to/add-github-oauth.md) for complete setup instructions.
+
 ## Sentry
 To enable Sentry, create a "src/sentryInstrumment.ts" file in your project.
 

package/dist/api.d.ts

@@ -1,6 +1,7 @@
 import express, { type NextFunction, type Request, type Response } from "express";
 import mongoose, { type Document, type Model } from "mongoose";
 import { type User } from "./auth";
+import { type ModelRouterValidationOptions } from "./openApiValidator";
 import { type RESTPermissions } from "./permissions";
 import type { PopulatePath } from "./populate";
 import { type TerrenoTransformer } from "./transformers";
@@ -203,14 +204,106 @@ export interface ModelRouterOptions<T> {
      * that you want to be documented and typed in the SDK.
      */
     openApiExtraModelProperties?: any;
+    /**
+     * Enable runtime validation of request bodies against the OpenAPI schema.
+     * When enabled, requests that don't match the documented schema will return 400 errors.
+     *
+     * Can be set to:
+     * - `true`: Enable validation for create and update operations
+     * - `false`: Disable validation (default)
+     * - Object with `validateCreate` and `validateUpdate` booleans for fine-grained control
+     *
+     * Note: Global validation can be enabled via `configureOpenApiValidator()`.
+     * This option overrides the global setting for this specific router.
+     */
+    validation?: boolean | ModelRouterValidationOptions;
+}
+/**
+ * Registration object returned by modelRouter when called with a path.
+ *
+ * Used with `TerrenoApp.register()` to mount model routers at specific paths.
+ * Contains the Express router and the path it should be mounted at.
+ *
+ * @see modelRouter for creating registrations
+ * @see TerrenoApp for registering routers
+ */
+export interface ModelRouterRegistration {
+    /** Internal type discriminator for registration detection */
+    __type: "modelRouter";
+    /** The path where the router should be mounted (e.g., "/todos") */
+    path: string;
+    /** The Express router containing CRUD endpoints */
+    router: express.Router;
 }
 /**
  * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
- * @param model A Mongoose Model
- * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
+ * When called with a path as the first argument, returns a `ModelRouterRegistration` that can be
+ * passed to `TerrenoApp.register()`.
+ *
+ * @example
+ * // Traditional usage (returns express.Router):
+ * router.use("/todos", modelRouter(Todo, options));
+ *
+ * // Registration usage (returns ModelRouterRegistration):
+ * const todoRouter = modelRouter("/todos", Todo, options);
+ * app.register(todoRouter);
  */
+export declare function modelRouter<T>(path: string, model: Model<T>, options: ModelRouterOptions<T>): ModelRouterRegistration;
 export declare function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router;
-export declare const asyncHandler: (fn: any) => (req: Request, res: Response, next: NextFunction) => Promise<any>;
+/**
+ * Options for the asyncHandler function.
+ */
+export interface AsyncHandlerOptions {
+    /**
+     * Schema for validating request body.
+     * When provided and validation is enabled, the request body will be validated
+     * against this schema before the handler runs.
+     */
+    bodySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+    /**
+     * Schema for validating query parameters.
+     * When provided and validation is enabled, query params will be validated
+     * against this schema before the handler runs.
+     */
+    querySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+    /**
+     * Override global validation setting for this handler.
+     * - `true`: Enable validation regardless of global setting
+     * - `false`: Disable validation regardless of global setting
+     * - `undefined`: Use global setting
+     */
+    validate?: boolean;
+}
+/**
+ * Wraps async route handlers to properly catch and forward errors.
+ *
+ * Since Express doesn't handle async routes well, wrap them with this function.
+ * Optionally supports integrated request validation.
+ *
+ * @param fn - The async route handler function
+ * @param options - Optional configuration for validation
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage without validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code
+ * }));
+ *
+ * // With integrated validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code - body is already validated
+ * }, {
+ *   bodySchema: {
+ *     name: {type: "string", required: true},
+ *     email: {type: "string", format: "email", required: true},
+ *   },
+ *   validate: true,
+ * }));
+ * ```
+ */
+export declare const asyncHandler: (fn: any, options?: AsyncHandlerOptions) => (req: Request, res: Response, next: NextFunction) => void;
 export declare const gooseRestRouter: typeof modelRouter;
 export type GooseRESTOptions<T> = ModelRouterOptions<T>;

package/dist/api.js

@@ -135,6 +135,7 @@ var auth_1 = require("./auth");
 var errors_1 = require("./errors");
 var logger_1 = require("./logger");
 var openApi_1 = require("./openApi");
+var openApiValidator_1 = require("./openApiValidator");
 var permissions_1 = require("./permissions");
 var transformers_1 = require("./transformers");
 var utils_1 = require("./utils");
@@ -227,13 +228,82 @@ function checkQueryParamAllowed(queryParam, queryParamValue, queryFields) {
 //
 //   return result;
 // }
-/**
- * Create a set of CRUD routes given a Mongoose model and configuration options.
- *
- * @param model A Mongoose Model
- * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
- */
-function modelRouter(model, options) {
+// Helper to determine if validation should be enabled for a specific operation.
+// When options.validation is not set, returns true — the middleware's own
+// isConfigured check will decide whether to actually validate.
+function shouldValidate(options, operation) {
+    var _a, _b, _c;
+    // Check route-specific validation option first
+    if (options.validation !== undefined) {
+        if (typeof options.validation === "boolean") {
+            return options.validation;
+        }
+        if (operation === "create") {
+            return (_a = options.validation.validateCreate) !== null && _a !== void 0 ? _a : true;
+        }
+        if (operation === "update") {
+            return (_b = options.validation.validateUpdate) !== null && _b !== void 0 ? _b : true;
+        }
+        return (_c = options.validation.validateQuery) !== null && _c !== void 0 ? _c : true;
+    }
+    // Default: let middleware's isConfigured check decide
+    return true;
+}
+// Get body validation middleware if validation is enabled
+function getBodyValidationMiddleware(model, options, operation) {
+    var validationOptions = {};
+    if (!shouldValidate(options, operation)) {
+        validationOptions.enabled = false;
+    }
+    if (typeof options.validation === "object") {
+        if (options.validation.onError) {
+            validationOptions.onError = options.validation.onError;
+        }
+        if (options.validation.onAdditionalPropertiesRemoved) {
+            validationOptions.onAdditionalPropertiesRemoved =
+                options.validation.onAdditionalPropertiesRemoved;
+        }
+        var excludeFields = operation === "create"
+            ? options.validation.excludeFromCreate
+            : options.validation.excludeFromUpdate;
+        if (excludeFields === null || excludeFields === void 0 ? void 0 : excludeFields.length) {
+            validationOptions.excludeFields = excludeFields;
+        }
+    }
+    return (0, openApiValidator_1.validateModelRequestBody)(model, validationOptions);
+}
+// Get query validation middleware if validation is enabled
+function getQueryValidationMiddleware(model, options) {
+    var querySchema = (0, openApiValidator_1.buildQuerySchemaFromFields)(model, options.queryFields);
+    var validationOptions = {};
+    if (!shouldValidate(options, "query")) {
+        validationOptions.enabled = false;
+    }
+    if (typeof options.validation === "object" && options.validation.onError) {
+        validationOptions.onError = options.validation.onError;
+    }
+    return (0, openApiValidator_1.validateQueryParams)(querySchema, validationOptions);
+}
+function modelRouter(pathOrModel, modelOrOptions, maybeOptions) {
+    var model;
+    var options;
+    var path;
+    if (typeof pathOrModel === "string") {
+        path = pathOrModel;
+        model = modelOrOptions;
+        options = maybeOptions;
+    }
+    else {
+        model = pathOrModel;
+        options = modelOrOptions;
+    }
+    var router = _buildModelRouter(model, options);
+    if (path !== undefined) {
+        return { __type: "modelRouter", path: path, router: router };
+    }
+    return router;
+}
+function _buildModelRouter(model, options) {
     var _this = this;
     var _a;
     var router = express_1.default.Router();
@@ -242,10 +312,15 @@ function modelRouter(model, options) {
         options.endpoints(router);
     }
     var responseHandler = (_a = options.responseHandler) !== null && _a !== void 0 ? _a : transformers_1.defaultResponseHandler;
+    // Always install validation middleware — they are no-ops until configureOpenApiValidator() is called
+    var createValidation = getBodyValidationMiddleware(model, options, "create");
+    var updateValidation = getBodyValidationMiddleware(model, options, "update");
+    var queryValidation = getQueryValidationMiddleware(model, options);
     router.post("/", [
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
         (0, openApi_1.createOpenApiMiddleware)(model, options),
         (0, permissions_1.permissionMiddleware)(model, options),
+        createValidation,
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
         var body, error_1, data, error_2, populateQuery, error_3, error_4, serialized, error_5;
         return __generator(this, function (_a) {
@@ -378,6 +453,7 @@ function modelRouter(model, options) {
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
         (0, permissions_1.permissionMiddleware)(model, options),
         (0, openApi_1.listOpenApiMiddleware)(model, options),
+        queryValidation,
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
         var query, _a, _b, queryParam, _c, _d, queryParam, queryFilter, error_6, limit, builtQuery, total, populatedQuery, data, error_7, serialized, error_8, more, msg;
         var e_4, _e, e_5, _f;
@@ -594,6 +670,7 @@ function modelRouter(model, options) {
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
         (0, openApi_1.patchOpenApiMiddleware)(model, options),
         (0, permissions_1.permissionMiddleware)(model, options),
+        updateValidation,
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
         var doc, body, error_10, prevDoc, error_11, populateQuery, error_12, serialized, error_13;
         var _a;
@@ -991,10 +1068,81 @@ function modelRouter(model, options) {
     router.use(errors_1.apiErrorMiddleware);
     return router;
 }
-// Since express doesn't handle async routes well, wrap them with this function.
-var asyncHandler = function (fn) { return function (req, res, next) {
-    return Promise.resolve(fn(req, res, next)).catch(next);
-}; };
+/**
+ * Wraps async route handlers to properly catch and forward errors.
+ *
+ * Since Express doesn't handle async routes well, wrap them with this function.
+ * Optionally supports integrated request validation.
+ *
+ * @param fn - The async route handler function
+ * @param options - Optional configuration for validation
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage without validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code
+ * }));
+ *
+ * // With integrated validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code - body is already validated
+ * }, {
+ *   bodySchema: {
+ *     name: {type: "string", required: true},
+ *     email: {type: "string", format: "email", required: true},
+ *   },
+ *   validate: true,
+ * }));
+ * ```
+ */
+var asyncHandler = function (fn, options) {
+    var _a, _b;
+    // If no validation options, return simple handler
+    if (!(options === null || options === void 0 ? void 0 : options.bodySchema) && !(options === null || options === void 0 ? void 0 : options.querySchema)) {
+        return function (req, res, next) {
+            return Promise.resolve(fn(req, res, next)).catch(next);
+        };
+    }
+    // Import validation functions dynamically to avoid circular deps at module load
+    var _c = require("./openApiValidator"), validateRequestBody = _c.validateRequestBody, validateQueryParams = _c.validateQueryParams, getOpenApiValidatorConfig = _c.getOpenApiValidatorConfig;
+    // Build validation middleware
+    var validators = [];
+    // Determine if validation should be enabled
+    var shouldValidate = (_b = (_a = options.validate) !== null && _a !== void 0 ? _a : getOpenApiValidatorConfig().validateRequests) !== null && _b !== void 0 ? _b : false;
+    if (shouldValidate) {
+        if (options.bodySchema) {
+            validators.push(validateRequestBody(options.bodySchema, { enabled: true }));
+        }
+        if (options.querySchema) {
+            validators.push(validateQueryParams(options.querySchema, { enabled: true }));
+        }
+    }
+    return function (req, res, next) {
+        // Run validators sequentially, then the handler
+        var runValidators = function (index) {
+            if (index >= validators.length) {
+                // All validators passed, run the actual handler
+                Promise.resolve(fn(req, res, next)).catch(next);
+                return;
+            }
+            try {
+                validators[index](req, res, function (err) {
+                    if (err) {
+                        next(err);
+                        return;
+                    }
+                    runValidators(index + 1);
+                });
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+        runValidators(0);
+    };
+};
 exports.asyncHandler = asyncHandler;
 // For backwards compatibility with the old names.
 exports.gooseRestRouter = modelRouter;