@terreno/api 0.15.1 → 0.16.0

package/dist/permissions.d.ts

@@ -1,7 +1,7 @@
 import type express from "express";
 import type { NextFunction } from "express";
-import { type Model } from "mongoose";
-import { type ModelRouterOptions, type RESTMethod } from "./api";
+import type { Model } from "mongoose";
+import type { ModelRouterOptions, RESTMethod } from "./api";
 import type { User } from "./auth";
 export type PermissionMethod<T> = (method: RESTMethod, user?: User, obj?: T) => boolean | Promise<boolean>;
 export interface RESTPermissions<T> {

package/dist/permissions.js

@@ -1,37 +1,4 @@
 "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 __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) {
@@ -79,14 +46,9 @@ var __values = (this && this.__values) || function(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.permissionMiddleware = exports.checkPermissions = exports.Permissions = exports.OwnerQueryFilter = void 0;
-var Sentry = __importStar(require("@sentry/bun"));
-var mongoose_1 = __importDefault(require("mongoose"));
-var api_1 = require("./api");
+var docLoader_1 = require("./docLoader");
 var errors_1 = require("./errors");
 var logger_1 = require("./logger");
 var OwnerQueryFilter = function (user) {
@@ -193,7 +155,7 @@ exports.checkPermissions = checkPermissions;
 // req.obj.
 var permissionMiddleware = function (model, options) {
     return function (req, _res, next) { return __awaiter(void 0, void 0, void 0, function () {
-        var method, reqMethod, builtQuery, populatedQuery, data, error_1, hiddenDoc, error, reason, error, error_2;
+        var method, reqMethod, data, error_1;
         var _a, _b;
         return __generator(this, function (_c) {
             switch (_c.label) {
@@ -203,7 +165,7 @@ var permissionMiddleware = function (model, options) {
                     }
                     _c.label = 1;
                 case 1:
-                    _c.trys.push([1, 10, , 11]);
+                    _c.trys.push([1, 5, , 6]);
                     method = void 0;
                     reqMethod = req.method.toLowerCase();
                     if (reqMethod === "post") {
@@ -242,69 +204,11 @@ var permissionMiddleware = function (model, options) {
                     if (method === "create" || method === "list") {
                         return [2 /*return*/, next()];
                     }
-                    builtQuery = model.findById(req.params.id);
-                    populatedQuery = (0, api_1.addPopulateToQuery)(
-                    // biome-ignore lint/suspicious/noExplicitAny: Query types vary based on populate paths
-                    builtQuery, options.populatePaths);
-                    data = void 0;
-                    _c.label = 3;
+                    return [4 /*yield*/, (0, docLoader_1.loadDocOr404)(model, req.params.id, options.populatePaths)];
                 case 3:
-                    _c.trys.push([3, 5, , 6]);
-                    return [4 /*yield*/, populatedQuery.exec()];
+                    data = _c.sent();
+                    return [4 /*yield*/, (0, exports.checkPermissions)(method, options.permissions[method], req.user, data)];
                 case 4:
-                    data = (_c.sent());
-                    return [3 /*break*/, 6];
-                case 5:
-                    error_1 = _c.sent();
-                    throw new errors_1.APIError({
-                        error: error_1,
-                        status: 500,
-                        title: "GET failed on ".concat(req.params.id),
-                    });
-                case 6:
-                    if (!!data) return [3 /*break*/, 8];
-                    return [4 /*yield*/, model.collection.findOne({
-                            _id: new mongoose_1.default.Types.ObjectId(req.params.id),
-                        })];
-                case 7:
-                    hiddenDoc = _c.sent();
-                    if (!hiddenDoc) {
-                        Sentry.captureMessage("Document ".concat(req.params.id, " not found for model ").concat(model.modelName));
-                        error = new errors_1.APIError({
-                            status: 404,
-                            title: "Document ".concat(req.params.id, " not found for model ").concat(model.modelName),
-                        });
-                        error.meta = undefined;
-                        throw error;
-                    }
-                    reason = null;
-                    if (hiddenDoc.deleted) {
-                        reason = { deleted: "true" };
-                    }
-                    else if (hiddenDoc.disabled) {
-                        reason = { disabled: "true" };
-                    }
-                    else if (hiddenDoc.archived) {
-                        reason = { archived: "true" };
-                    }
-                    // If no reason found, treat as not found
-                    if (!reason) {
-                        error = new errors_1.APIError({
-                            status: 404,
-                            title: "Document ".concat(req.params.id, " not found for model ").concat(model.modelName),
-                        });
-                        error.meta = undefined;
-                        throw error;
-                    }
-                    throw new errors_1.APIError({
-                        // We don't want to send this to Sentry because it's expected behavior.
-                        disableExternalErrorTracking: true,
-                        meta: reason,
-                        status: 404,
-                        title: "Document ".concat(req.params.id, " not found for model ").concat(model.modelName),
-                    });
-                case 8: return [4 /*yield*/, (0, exports.checkPermissions)(method, options.permissions[method], req.user, data)];
-                case 9:
                     if (!(_c.sent())) {
                         throw new errors_1.APIError({
                             status: 403,
@@ -313,11 +217,11 @@ var permissionMiddleware = function (model, options) {
                     }
                     req.obj = data;
                     return [2 /*return*/, next()];
-                case 10:
-                    error_2 = _c.sent();
-                    logger_1.logger.error("Permissions error: ".concat(error_2 instanceof Error ? error_2.message : error_2));
-                    return [2 /*return*/, next(error_2)];
-                case 11: return [2 /*return*/];
+                case 5:
+                    error_1 = _c.sent();
+                    logger_1.logger.error("Permissions error: ".concat(error_1 instanceof Error ? error_1.message : error_1));
+                    return [2 /*return*/, next(error_1)];
+                case 6: return [2 /*return*/];
             }
         });
     }); };

package/dist/zodOpenApi.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/zodOpenApi.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.z = void 0;
+var zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
+var zod_1 = require("zod");
+Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
+(0, zod_to_openapi_1.extendZodWithOpenApi)(zod_1.z);

package/package.json

@@ -4,6 +4,7 @@
     "url": "https://github.com/FlourishHealth/terreno/issues"
   },
   "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.5.0",
     "@sentry/bun": "^10.25.0",
     "@sentry/profiling-node": "^10.25.0",
     "@types/qs": "^6.14.0",
@@ -67,7 +68,8 @@
     "sinon": "^21.0.1",
     "supertest": "^7.0.0",
     "typedoc": "~0.28.17",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "zod": "^4.3.6"
   },
   "homepage": "https://github.com/FlourishHealth/terreno#readme",
   "keywords": [
@@ -83,7 +85,8 @@
     "access": "public"
   },
   "peerDependencies": {
-    "mongoose": "^8.0.0 || ^9.0.0"
+    "mongoose": "^8.0.0 || ^9.0.0",
+    "zod": "^4.3.6"
   },
   "repository": {
     "type": "git",
@@ -106,5 +109,5 @@
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.15.1"
+  "version": "0.16.0"
 }

package/src/actions.openApi.test.ts

@@ -0,0 +1,176 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+import {beforeEach, describe, expect, it} from "bun:test";
+import type express from "express";
+import supertest from "supertest";
+import {type ModelRouterOptions, modelRouter} from "./api";
+import {addAuthRoutes, setupAuth} from "./auth";
+import {setupServer} from "./expressServer";
+import {Permissions} from "./permissions";
+import {TerrenoApp} from "./terrenoApp";
+import {authAsUser, FoodModel, setupDb, UserModel} from "./tests";
+import {z} from "./zodOpenApi";
+
+const foodActionPermissions = {
+  create: [Permissions.IsAny],
+  delete: [Permissions.IsAny],
+  list: [Permissions.IsAny],
+  read: [Permissions.IsAny],
+  update: [Permissions.IsAny],
+};
+
+const foodActionRouterOptions = {
+  allowAnonymous: true,
+  collectionActions: {
+    summarize: {
+      body: z
+        .object({
+          label: z.string(),
+        })
+        .strict(),
+      handler: async ({body}) => ({label: (body as {label: string}).label, total: 1}),
+      method: "POST" as const,
+      permissions: [Permissions.IsAny],
+      response: z.object({label: z.string(), total: z.number()}).strict(),
+      summary: "Summarize foods collection",
+      tag: "CustomFoodTag",
+    },
+  },
+  instanceActions: {
+    ping: {
+      handler: async ({doc}) => ({id: String(doc._id)}),
+      method: "GET" as const,
+      permissions: [Permissions.IsAny],
+      response: z.object({id: z.string()}),
+      summary: "Ping a food document",
+    },
+  },
+  permissions: foodActionPermissions,
+  sort: "-created",
+};
+
+const primeActionOpenApiRoutes = async (
+  server: ReturnType<typeof supertest>,
+  foodId: string
+): Promise<void> => {
+  await server.get(`/food/${foodId}/ping`).expect(200);
+  await server.post("/food/summarize").send({label: "test"}).expect(200);
+};
+
+const assertActionOpenApiSpec = (spec: Record<string, unknown>): void => {
+  const paths = spec.paths as Record<string, Record<string, unknown>>;
+  const collectionPath = paths["/food/summarize"];
+  const instancePath = paths["/food/{id}/ping"];
+
+  expect(collectionPath?.post).toBeDefined();
+  expect(instancePath?.get).toBeDefined();
+
+  const collectionOp = collectionPath.post as Record<string, unknown>;
+  const instanceOp = instancePath.get as Record<string, unknown>;
+
+  expect(collectionOp.operationId).toBe("CustomFoodTag_summarize");
+  expect(collectionOp.tags).toEqual(["CustomFoodTag"]);
+  expect(collectionOp.summary).toBe("Summarize foods collection");
+
+  expect(instanceOp.operationId).toBe("foods_ping");
+  expect(instanceOp.tags).toEqual(["foods"]);
+  expect(instanceOp.summary).toBe("Ping a food document");
+
+  const collectionParams = (collectionOp.parameters as {in: string; name: string}[]) ?? [];
+  expect(collectionParams.some((p) => p.in === "path" && p.name === "id")).toBe(false);
+
+  const instanceParams =
+    (instanceOp.parameters as {in: string; name: string; required?: boolean}[]) ?? [];
+  const idParam = instanceParams.find((p) => p.in === "path" && p.name === "id");
+  expect(idParam).toBeDefined();
+  expect(idParam?.required).toBe(true);
+
+  const collectionRequestSchema = (
+    collectionOp.requestBody as {
+      content: {"application/json": {schema: {properties: {label: unknown}}}};
+    }
+  ).content["application/json"].schema;
+  expect(collectionRequestSchema.properties?.label).toBeDefined();
+
+  const collectionResponseSchema = (
+    collectionOp.responses as {
+      "200": {content: {"application/json": {schema: {properties: {data: unknown}}}}};
+    }
+  )["200"].content["application/json"].schema;
+  expect(collectionResponseSchema.properties?.data).toBeDefined();
+
+  const instanceResponseSchema = (
+    instanceOp.responses as {
+      "200": {content: {"application/json": {schema: {properties: {data: unknown}}}}};
+    }
+  )["200"].content["application/json"].schema;
+  expect(instanceResponseSchema.properties?.data).toBeDefined();
+};
+
+describe("action OpenAPI emission", () => {
+  let admin: Awaited<ReturnType<typeof setupDb>>[0];
+  let foodId: string;
+
+  beforeEach(async () => {
+    process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
+    process.env.ENABLE_SWAGGER = "true";
+    [admin] = await setupDb();
+    const food = await FoodModel.create({
+      calories: 1,
+      hidden: false,
+      name: "OpenApiFood",
+      ownerId: admin._id,
+      source: {name: "test"},
+    });
+    foodId = String(food._id);
+  });
+
+  describe("TerrenoApp", () => {
+    it("includes action operations in openapi.json after first request", async () => {
+      const foodRegistration = modelRouter("/food", FoodModel, foodActionRouterOptions);
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      })
+        .register(foodRegistration)
+        .build();
+
+      const server = supertest(app);
+      await primeActionOpenApiRoutes(server, foodId);
+
+      const specRes = await server.get("/openapi.json").expect(200);
+      assertActionOpenApiSpec(specRes.body);
+    });
+  });
+
+  describe("setupServer", () => {
+    let app: express.Application;
+
+    beforeEach(() => {
+      const addRoutes = (
+        router: express.Router,
+        routerOptions?: Partial<ModelRouterOptions<unknown>>
+      ): void => {
+        router.use(
+          "/food",
+          modelRouter(FoodModel as any, {...foodActionRouterOptions, ...routerOptions})
+        );
+      };
+
+      app = setupServer({
+        addRoutes,
+        skipListen: true,
+        userModel: UserModel as any,
+      });
+      setupAuth(app, UserModel as any);
+      addAuthRoutes(app, UserModel as any);
+    });
+
+    it("emits the same action operations on first hit via legacy setupServer", async () => {
+      const server = supertest(app);
+      await primeActionOpenApiRoutes(server, foodId);
+
+      const specRes = await server.get("/openapi.json").expect(200);
+      assertActionOpenApiSpec(specRes.body);
+    });
+  });
+});