@terreno/api 0.0.4 → 0.0.11-beta.1

package/CLAUDE.md

@@ -0,0 +1,107 @@
+# @terreno/api
+
+REST API framework built on Express/Mongoose, styled after Django REST Framework.
+
+## Commands
+
+```bash
+bun run compile          # Compile TypeScript
+bun run dev              # Watch mode
+bun run test             # Run tests
+bun run lint             # Lint code
+bun run lint:fix         # Fix lint issues
+```
+
+## Architecture
+
+### modelRouter
+
+Automatically creates RESTful CRUD APIs for Mongoose models with built-in permissions, population, filtering, and lifecycle hooks.
+
+```typescript
+import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
+
+const router = modelRouter(YourModel, {
+  permissions: {
+    list: [Permissions.IsAuthenticated],
+    create: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+    delete: [],  // Disabled
+  },
+  sort: "-created",
+  queryFields: ["_id", "type", "name"],
+});
+```
+
+### Custom Routes
+
+For non-CRUD endpoints, use the OpenAPI builder:
+
+```typescript
+import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
+
+router.get("/yourRoute/:id", [
+  authenticateMiddleware(),
+  createOpenApiBuilder(options)
+    .withTags(["yourTag"])
+    .withSummary("Brief summary")
+    .withPathParameter("id", {type: "string"})
+    .withResponse(200, {data: {type: "object"}})
+    .build(),
+], asyncHandler(async (req, res) => {
+  return res.json({data: result});
+}));
+```
+
+## Conventions
+
+### Error Handling
+- Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
+- Services should throw user-friendly errors
+
+### Mongoose
+- Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
+- Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
+- All model types live in `src/modelInterfaces.ts`
+
+### User Type Casting
+- In API routes: `req.user` is `UserDocument | undefined`
+- In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
+- Never use `as any as UserDocument`
+
+### Logging
+- Use `logger.info/warn/error/debug` for permanent logs (not `console.log`)
+
+### Testing
+- Use bun test with expect for testing
+- Use existing manual mocks from `src/__mocks__/`
+- Never mock @terreno/api or models
+
+## Model Type Generation
+
+When creating/modifying Mongoose models, update `src/modelInterfaces.ts`:
+
+```typescript
+export type YourModelMethods = {
+  customMethod: (this: YourModelDocument, param: string) => Promise<void>;
+};
+
+export type YourModelStatics = DefaultStatics<YourModelDocument> & {
+  customStatic: (this: YourModelModel, param: string) => Promise<YourModelDocument>;
+};
+
+export type YourModelModel = DefaultModel<YourModelDocument> & YourModelStatics;
+export type YourModelSchema = mongoose.Schema<YourModelDocument, YourModelModel, YourModelMethods>;
+export type YourModelDocument = DefaultDoc & YourModelMethods & {
+  fieldName: string;
+};
+```
+
+## SDK Generation
+
+After modifying routes, regenerate the SDK:
+
+```bash
+bun run sdk
+```

package/bunfig.toml

@@ -1,6 +1,7 @@
 [test]
 preload = ["./src/tests/bunSetup.ts"]
 root = "./src"
-coverageExclude = ["dist/**"]
-# Note: No coverageThreshold set - tests will not fail on low coverage
+coverage = true
+coverageExclude = ["dist/**", "**/*.test.ts", "**/tests/**"]
+coverageThreshold = { line = 80, function = 80 }
 

package/dist/api.d.ts

@@ -22,7 +22,7 @@ export type RESTMethod = "list" | "create" | "read" | "update" | "delete";
  * This is the main configuration.
  * @param T - the base document type. This should not include Mongoose models, just the types of the object.
  */
-export interface modelRouterOptions<T> {
+export interface ModelRouterOptions<T> {
     /**
      * A group of method-level (create/read/update/delete/list) permissions.
      * Determine if the user can perform the operation at all, and for read/update/delete methods,
@@ -180,17 +180,7 @@ export interface modelRouterOptions<T> {
      * This is a good spot to remove sensitive information from the object, such as passwords or API
      * keys. Throw an APIError to return a 400 with an error message.
      */
-    responseHandler?: (value: (Document<any, any, any> & T) | (Document<any, any, any> & T)[], method: "list" | "create" | "read" | "update" | "delete", request: express.Request, options: modelRouterOptions<T>) => Promise<JSONValue>;
-    /**
-     * The discriminatorKey that you passed when creating the Mongoose models. Defaults to __t. See:
-     * https://mongoosejs.com/docs/discriminators.html If this key is provided,
-     * you must provide the same key as part of the top level of the body when making performing
-     * update or delete operations on this model.
-     *    \{discriminatorKey: "__t"\}
-     *
-     *     PATCH \{__t: "SuperUser", name: "Foo"\} // __t is required or there will be a 404 error.
-     */
-    discriminatorKey?: string;
+    responseHandler?: (value: (Document<any, any, any> & T) | (Document<any, any, any> & T)[], method: "list" | "create" | "read" | "update" | "delete", request: express.Request, options: ModelRouterOptions<T>) => Promise<JSONValue>;
     /**
      * The OpenAPI generator for this server. This is used to generate the OpenAPI documentation.
      */
@@ -214,14 +204,13 @@ export interface modelRouterOptions<T> {
      */
     openApiExtraModelProperties?: any;
 }
-export declare function getModel(baseModel: Model<any>, body?: any, options?: modelRouterOptions<any>): mongoose.Model<any, {}, {}, {}, any, any, any>;
 /**
- * Create a set of CRUD routes given a Mongoose model $baseModel and configuration options.
+ * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
- * @param baseModel A Mongoose Model
+ * @param model A Mongoose Model
  * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
  */
-export declare function modelRouter<T>(baseModel: Model<T>, options: modelRouterOptions<T>): express.Router;
+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>;
 export declare const gooseRestRouter: typeof modelRouter;
-export type GooseRESTOptions<T> = modelRouterOptions<T>;
+export type GooseRESTOptions<T> = ModelRouterOptions<T>;

package/dist/api.js

@@ -121,7 +121,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.gooseRestRouter = exports.asyncHandler = void 0;
 exports.addPopulateToQuery = addPopulateToQuery;
-exports.getModel = getModel;
 exports.modelRouter = modelRouter;
 /**
  * This is the doc comment for api.ts
@@ -168,21 +167,6 @@ function addPopulateToQuery(builtQuery, populatePaths) {
 var PAGINATION_QUERY_PARAMS = ["limit", "page", "sort"];
 // Add support for more complex queries.
 var COMPLEX_QUERY_PARAMS = ["$and", "$or"];
-// A function to decide which model to use. If no discriminators are provided,
-// just returns the base model. If
-function getModel(baseModel, body, options) {
-    var _a, _b;
-    var discriminatorKey = (_a = options === null || options === void 0 ? void 0 : options.discriminatorKey) !== null && _a !== void 0 ? _a : "__t";
-    var modelName = body === null || body === void 0 ? void 0 : body[discriminatorKey];
-    if (!modelName) {
-        return baseModel;
-    }
-    var model = (_b = baseModel.discriminators) === null || _b === void 0 ? void 0 : _b[modelName];
-    if (!model) {
-        throw new Error("Could not find discriminator model for key ".concat(modelName, ", baseModel: ").concat(baseModel));
-    }
-    return model;
-}
 // Ensures query params are allowed. Also checks nested query params when using $and/$or.
 function checkQueryParamAllowed(queryParam, queryParamValue, queryFields) {
     var e_2, _a, e_3, _b;
@@ -244,12 +228,12 @@ function checkQueryParamAllowed(queryParam, queryParamValue, queryFields) {
 //   return result;
 // }
 /**
- * Create a set of CRUD routes given a Mongoose model $baseModel and configuration options.
+ * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
- * @param baseModel A Mongoose Model
+ * @param model A Mongoose Model
  * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
  */
-function modelRouter(baseModel, options) {
+function modelRouter(model, options) {
     var _this = this;
     var _a;
     var router = express_1.default.Router();
@@ -260,15 +244,13 @@ function modelRouter(baseModel, options) {
     var responseHandler = (_a = options.responseHandler) !== null && _a !== void 0 ? _a : transformers_1.defaultResponseHandler;
     router.post("/", [
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
-        (0, openApi_1.createOpenApiMiddleware)(baseModel, options),
-        (0, permissions_1.permissionMiddleware)(baseModel, options),
+        (0, openApi_1.createOpenApiMiddleware)(model, options),
+        (0, permissions_1.permissionMiddleware)(model, options),
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-        var model, body, error_1, data, error_2, populateQuery, error_3, error_4, serialized, error_5;
-        var _a;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        var body, error_1, data, error_2, populateQuery, error_3, error_4, serialized, error_5;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
                 case 0:
-                    model = getModel(baseModel, (_a = req.body) === null || _a === void 0 ? void 0 : _a.__t, options);
                     try {
                         body = (0, transformers_1.transform)(options, req.body, "create", req.user);
                     }
@@ -281,15 +263,15 @@ function modelRouter(baseModel, options) {
                         });
                     }
                     if (!options.preCreate) return [3 /*break*/, 5];
-                    _b.label = 1;
+                    _a.label = 1;
                 case 1:
-                    _b.trys.push([1, 3, , 4]);
+                    _a.trys.push([1, 3, , 4]);
                     return [4 /*yield*/, options.preCreate(body, req)];
                 case 2:
-                    body = _b.sent();
+                    body = _a.sent();
                     return [3 /*break*/, 4];
                 case 3:
-                    error_1 = _b.sent();
+                    error_1 = _a.sent();
                     if ((0, errors_1.isAPIError)(error_1)) {
                         throw error_1;
                     }
@@ -314,7 +296,7 @@ function modelRouter(baseModel, options) {
                             title: "Create not allowed",
                         });
                     }
-                    _b.label = 5;
+                    _a.label = 5;
                 case 5:
                     if (body === undefined) {
                         throw new errors_1.APIError({
@@ -323,15 +305,15 @@ function modelRouter(baseModel, options) {
                             title: "Invalid request body",
                         });
                     }
-                    _b.label = 6;
+                    _a.label = 6;
                 case 6:
-                    _b.trys.push([6, 8, , 9]);
+                    _a.trys.push([6, 8, , 9]);
                     return [4 /*yield*/, model.create(body)];
                 case 7:
-                    data = _b.sent();
+                    data = _a.sent();
                     return [3 /*break*/, 9];
                 case 8:
-                    error_2 = _b.sent();
+                    error_2 = _a.sent();
                     throw new errors_1.APIError({
                         disableExternalErrorTracking: (0, errors_1.getDisableExternalErrorTracking)(error_2),
                         error: error_2,
@@ -340,17 +322,17 @@ function modelRouter(baseModel, options) {
                     });
                 case 9:
                     if (!options.populatePaths) return [3 /*break*/, 13];
-                    _b.label = 10;
+                    _a.label = 10;
                 case 10:
-                    _b.trys.push([10, 12, , 13]);
+                    _a.trys.push([10, 12, , 13]);
                     populateQuery = model.findById(data._id);
                     populateQuery = addPopulateToQuery(populateQuery, options.populatePaths);
                     return [4 /*yield*/, populateQuery.exec()];
                 case 11:
-                    data = _b.sent();
+                    data = _a.sent();
                     return [3 /*break*/, 13];
                 case 12:
-                    error_3 = _b.sent();
+                    error_3 = _a.sent();
                     throw new errors_1.APIError({
                         disableExternalErrorTracking: (0, errors_1.getDisableExternalErrorTracking)(error_3),
                         error: error_3,
@@ -359,15 +341,15 @@ function modelRouter(baseModel, options) {
                     });
                 case 13:
                     if (!options.postCreate) return [3 /*break*/, 17];
-                    _b.label = 14;
+                    _a.label = 14;
                 case 14:
-                    _b.trys.push([14, 16, , 17]);
+                    _a.trys.push([14, 16, , 17]);
                     return [4 /*yield*/, options.postCreate(data, req)];
                 case 15:
-                    _b.sent();
+                    _a.sent();
                     return [3 /*break*/, 17];
                 case 16:
-                    error_4 = _b.sent();
+                    error_4 = _a.sent();
                     throw new errors_1.APIError({
                         disableExternalErrorTracking: (0, errors_1.getDisableExternalErrorTracking)(error_4),
                         error: error_4,
@@ -375,13 +357,13 @@ function modelRouter(baseModel, options) {
                         title: "postCreate hook error: ".concat(error_4.message),
                     });
                 case 17:
-                    _b.trys.push([17, 19, , 20]);
+                    _a.trys.push([17, 19, , 20]);
                     return [4 /*yield*/, responseHandler(data, "create", req, options)];
                 case 18:
-                    serialized = _b.sent();
+                    serialized = _a.sent();
                     return [2 /*return*/, res.status(201).json({ data: serialized })];
                 case 19:
-                    error_5 = _b.sent();
+                    error_5 = _a.sent();
                     throw new errors_1.APIError({
                         disableExternalErrorTracking: (0, errors_1.getDisableExternalErrorTracking)(error_5),
                         error: error_5,
@@ -394,16 +376,15 @@ function modelRouter(baseModel, options) {
     // TODO add rate limit
     router.get("/", [
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
-        (0, permissions_1.permissionMiddleware)(baseModel, options),
-        (0, openApi_1.listOpenApiMiddleware)(baseModel, options),
+        (0, permissions_1.permissionMiddleware)(model, options),
+        (0, openApi_1.listOpenApiMiddleware)(model, options),
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-        var model, query, _a, _b, queryParam, _c, _d, queryParam, queryFilter, error_6, limit, builtQuery, total, populatedQuery, data, error_7, serialized, error_8, more, msg;
+        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;
         var _g, _h, _j, _k, _l, _m;
         return __generator(this, function (_o) {
             switch (_o.label) {
                 case 0:
-                    model = baseModel;
                     query = {};
                     try {
                         for (_a = __values(Object.keys((_g = options.defaultQueryParams) !== null && _g !== void 0 ? _g : [])), _b = _a.next(); !_b.done; _b = _a.next()) {
@@ -575,8 +556,8 @@ function modelRouter(baseModel, options) {
     }); }));
     router.get("/:id", [
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
-        (0, openApi_1.getOpenApiMiddleware)(baseModel, options),
-        (0, permissions_1.permissionMiddleware)(baseModel, options),
+        (0, openApi_1.getOpenApiMiddleware)(model, options),
+        (0, permissions_1.permissionMiddleware)(model, options),
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
         var data, serialized, error_9;
         return __generator(this, function (_a) {
@@ -611,15 +592,14 @@ function modelRouter(baseModel, options) {
     }); }));
     router.patch("/:id", [
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
-        (0, openApi_1.patchOpenApiMiddleware)(baseModel, options),
-        (0, permissions_1.permissionMiddleware)(baseModel, options),
+        (0, openApi_1.patchOpenApiMiddleware)(model, options),
+        (0, permissions_1.permissionMiddleware)(model, options),
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-        var model, doc, body, error_10, prevDoc, error_11, populateQuery, error_12, serialized, error_13;
+        var doc, body, error_10, prevDoc, error_11, populateQuery, error_12, serialized, error_13;
         var _a;
         return __generator(this, function (_b) {
             switch (_b.label) {
                 case 0:
-                    model = getModel(baseModel, req.body, options);
                     doc = req.obj;
                     try {
                         body = (0, transformers_1.transform)(options, req.body, "update", req.user);
@@ -733,14 +713,13 @@ function modelRouter(baseModel, options) {
     }); }));
     router.delete("/:id", [
         (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
-        (0, openApi_1.deleteOpenApiMiddleware)(baseModel, options),
-        (0, permissions_1.permissionMiddleware)(baseModel, options),
+        (0, openApi_1.deleteOpenApiMiddleware)(model, options),
+        (0, permissions_1.permissionMiddleware)(model, options),
     ], (0, exports.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-        var model, doc, body, error_14, error_15, error_16;
+        var doc, body, error_14, error_15, error_16;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
-                    model = getModel(baseModel, req.body, options);
                     doc = req.obj;
                     if (!options.preDelete) return [3 /*break*/, 5];
                     body = void 0;
@@ -823,15 +802,14 @@ function modelRouter(baseModel, options) {
     }); }));
     function arrayOperation(req, res, operation) {
         return __awaiter(this, void 0, void 0, function () {
-            var model, doc, prevDoc, field, array, index, body, error_17, error_18, error_19;
+            var doc, prevDoc, field, array, index, body, error_17, error_18, error_19;
             var _a;
             var _b, _c;
             return __generator(this, function (_d) {
                 switch (_d.label) {
-                    case 0:
-                        model = getModel(baseModel, req.body, options);
-                        return [4 /*yield*/, (0, permissions_1.checkPermissions)("update", options.permissions.update, req.user)];
+                    case 0: return [4 /*yield*/, (0, permissions_1.checkPermissions)("update", options.permissions.update, req.user)];
                     case 1:
+                        // TODO Combine array operations and .patch(), as they are very similar.
                         if (!(_d.sent())) {
                             throw new errors_1.APIError({
                                 status: 405,
@@ -842,9 +820,7 @@ function modelRouter(baseModel, options) {
                     case 2:
                         doc = _d.sent();
                         prevDoc = (0, cloneDeep_1.default)(doc);
-                        // We fail here because we might fetch the document without the __t but we'd be missing all the
-                        // hooks.
-                        if (!doc || (doc.__t && !req.body.__t)) {
+                        if (!doc) {
                             throw new errors_1.APIError({
                                 status: 404,
                                 title: "Could not find document to PATCH: ".concat(req.params.id),
@@ -1007,7 +983,7 @@ function modelRouter(baseModel, options) {
         });
     }
     // Set up routes for managing array fields. Check if there any array fields to add this for.
-    if (Object.values(baseModel.schema.paths).find(function (config) { return config.instance === "Array"; })) {
+    if (Object.values(model.schema.paths).find(function (config) { return config.instance === "Array"; })) {
         router.post("/:id/:field", (0, auth_1.authenticateMiddleware)(options.allowAnonymous), (0, exports.asyncHandler)(arrayPost));
         router.patch("/:id/:field/:itemId", (0, auth_1.authenticateMiddleware)(options.allowAnonymous), (0, exports.asyncHandler)(arrayPatch));
         router.delete("/:id/:field/:itemId", (0, auth_1.authenticateMiddleware)(options.allowAnonymous), (0, exports.asyncHandler)(arrayDelete));