@terreno/api 0.15.1 → 0.15.2

package/src/consentApp.ts

@@ -8,6 +8,7 @@
 
 import {type Application, Router} from "express";
 import {DateTime} from "luxon";
+import type {CollectionActionConfig} from "./actions";
 import {asyncHandler, modelRouter} from "./api";
 import type {User} from "./auth";
 import {authenticateMiddleware} from "./auth";
@@ -40,6 +41,12 @@ export interface ConsentAppOptions {
   supportedLocales?: string[];
 }
 
+const requireAdmin = (user: User | undefined): void => {
+  if (!user?.admin) {
+    throw new APIError({status: 403, title: "Admin access required"});
+  }
+};
+
 export class ConsentApp implements TerrenoPlugin {
   private options: ConsentAppOptions;
 
@@ -50,79 +57,76 @@ export class ConsentApp implements TerrenoPlugin {
   register(app: Application): void {
     const {auditTrail, resolveConsentForms, aiConfig} = this.options;
 
-    // Admin CRUD for consent forms
-    app.use(
-      "/consent-forms",
-      modelRouter(ConsentForm, {
-        endpoints: (router) => {
-          if (aiConfig) {
-            // POST /consent-forms/generate - generate consent form content with AI
-            router.post(
-              "/generate",
-              authenticateMiddleware(),
-              asyncHandler(async (req, res) => {
-                const user = req.user as User | undefined;
-                if (!user?.admin) {
-                  throw new APIError({status: 403, title: "Admin access required"});
-                }
-
-                const {type, description, locale = "en"} = req.body;
-                if (!type) {
-                  throw new APIError({status: 400, title: "type is required"});
-                }
-                if (!description) {
-                  throw new APIError({status: 400, title: "description is required"});
-                }
-
-                const content = await aiConfig.generateContent({description, locale, type});
-
-                logger.info("ConsentForm content generated", {locale, type});
-
-                return res.json({data: {content}});
-              })
-            );
-
-            // POST /consent-forms/translate - translate consent form content with AI
-            router.post(
-              "/translate",
-              authenticateMiddleware(),
-              asyncHandler(async (req, res) => {
-                const user = req.user as User | undefined;
-                if (!user?.admin) {
-                  throw new APIError({status: 403, title: "Admin access required"});
-                }
-
-                const {content, fromLocale, toLocale} = req.body;
-                if (!content) {
-                  throw new APIError({status: 400, title: "content is required"});
-                }
-                if (!fromLocale) {
-                  throw new APIError({status: 400, title: "fromLocale is required"});
-                }
-                if (!toLocale) {
-                  throw new APIError({status: 400, title: "toLocale is required"});
-                }
-
-                const translated = await aiConfig.translateContent({content, fromLocale, toLocale});
+    const collectionActions: Record<string, CollectionActionConfig<unknown, unknown, unknown>> = {};
 
-                logger.info("ConsentForm content translated", {fromLocale, toLocale});
-
-                return res.json({data: {content: translated}});
-              })
-            );
+    if (aiConfig) {
+      collectionActions.generate = {
+        handler: async ({body, user}) => {
+          requireAdmin(user);
+          const typedBody = body as {type?: string; description?: string; locale?: string};
+          if (!typedBody.type) {
+            throw new APIError({status: 400, title: "type is required"});
           }
+          if (!typedBody.description) {
+            throw new APIError({status: 400, title: "description is required"});
+          }
+          const locale = typedBody.locale ?? "en";
+          const content = await aiConfig.generateContent({
+            description: typedBody.description,
+            locale,
+            type: typedBody.type,
+          });
+          logger.info("ConsentForm content generated", {locale, type: typedBody.type});
+          return {content};
+        },
+        method: "POST",
+        permissions: [Permissions.IsAuthenticated],
+        summary: "Generate consent form content with AI",
+      };
+
+      collectionActions.translate = {
+        handler: async ({body, user}) => {
+          requireAdmin(user);
+          const typedBody = body as {
+            content?: string;
+            fromLocale?: string;
+            toLocale?: string;
+          };
+          if (!typedBody.content) {
+            throw new APIError({status: 400, title: "content is required"});
+          }
+          if (!typedBody.fromLocale) {
+            throw new APIError({status: 400, title: "fromLocale is required"});
+          }
+          if (!typedBody.toLocale) {
+            throw new APIError({status: 400, title: "toLocale is required"});
+          }
+          const translated = await aiConfig.translateContent({
+            content: typedBody.content,
+            fromLocale: typedBody.fromLocale,
+            toLocale: typedBody.toLocale,
+          });
+          logger.info("ConsentForm content translated", {
+            fromLocale: typedBody.fromLocale,
+            toLocale: typedBody.toLocale,
+          });
+          return {content: translated};
+        },
+        method: "POST",
+        permissions: [Permissions.IsAuthenticated],
+        summary: "Translate consent form content with AI",
+      };
+    }
 
-          // POST /consent-forms/:id/publish - clone form with incremented version and activate
-          router.post(
-            "/:id/publish",
-            authenticateMiddleware(),
-            asyncHandler(async (req, res) => {
-              const user = req.user as User | undefined;
-              if (!user?.admin) {
-                throw new APIError({status: 403, title: "Admin access required"});
-              }
-
-              const form = await ConsentForm.findExactlyOne({_id: req.params.id});
+    app.use(
+      "/consent-forms",
+      modelRouter(ConsentForm, {
+        collectionActions,
+        instanceActions: {
+          publish: {
+            handler: async ({doc, user}) => {
+              requireAdmin(user);
+              const form = doc as ConsentFormDocument;
 
               const newFormData = {
                 active: true,
@@ -144,7 +148,6 @@ export class ConsentApp implements TerrenoPlugin {
 
               const newForm = await ConsentForm.create(newFormData);
 
-              // Deactivate all other versions of the same slug
               await ConsentForm.updateMany(
                 {_id: {$ne: newForm._id}, slug: form.slug},
                 {active: false}
@@ -155,9 +158,12 @@ export class ConsentApp implements TerrenoPlugin {
                 slug: newForm.slug,
               });
 
-              return res.json({data: newForm});
-            })
-          );
+              return newForm;
+            },
+            method: "POST",
+            permissions: [Permissions.IsAuthenticated],
+            summary: "Publish a new version of a consent form",
+          },
         },
         permissions: {
           create: [Permissions.IsAdmin],
@@ -229,7 +235,6 @@ export class ConsentApp implements TerrenoPlugin {
           respondedFormVersions.set(formId, response.formVersionSnapshot ?? 0);
         }
 
-        // Fetch the forms corresponding to existing responses to check version matches
         const respondedFormIds = existingResponses.map((r) => r.consentFormId);
         const respondedForms = await ConsentForm.find({_id: {$in: respondedFormIds}});
         const formVersionByFormId = new Map<string, number>();
@@ -237,17 +242,14 @@ export class ConsentApp implements TerrenoPlugin {
           formVersionByFormId.set(form._id.toString(), form.version);
         }
 
-        // Filter out forms where the user already has a response matching the current version
         const pendingForms = resolvedForms.filter((form) => {
           const formId = form._id.toString();
-          // Find responses for this form
           const matchingResponses = existingResponses.filter(
             (r) => r.consentFormId.toString() === formId
           );
           if (matchingResponses.length === 0) {
             return true;
           }
-          // Check if any response matches the current form version
           return !matchingResponses.some((r) => r.formVersionSnapshot === form.version);
         });
 
@@ -300,7 +302,6 @@ export class ConsentApp implements TerrenoPlugin {
           throw new APIError({status: 400, title: "Consent form is not active"});
         }
 
-        // Validate signature requirement
         if (form.captureSignature && agreed && !signature) {
           throw new APIError({
             status: 400,
@@ -308,7 +309,6 @@ export class ConsentApp implements TerrenoPlugin {
           });
         }
 
-        // Validate required checkboxes
         if (agreed && form.checkboxes.length > 0) {
           const values = checkboxValues ?? {};
           for (let i = 0; i < form.checkboxes.length; i++) {
@@ -409,7 +409,6 @@ export class ConsentApp implements TerrenoPlugin {
       })
     );
 
-    // GET /consents/audit/:userId - admin audit trail for a specific user
     if (auditTrail) {
       router.get(
         "/audit/:userId",

package/src/docLoader.test.ts

@@ -0,0 +1,58 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+import {describe, expect, it, mock} from "bun:test";
+import {loadDocOr404} from "./docLoader";
+import {APIError} from "./errors";
+
+describe("loadDocOr404", () => {
+  it("returns hidden reason metadata when document is deleted", async () => {
+    const model = {
+      collection: {findOne: mock(async () => ({deleted: true}))},
+      findById: mock(() => ({exec: mock(async () => null)})),
+      modelName: "MockModel",
+    } as any;
+
+    try {
+      await loadDocOr404(model, "507f1f77bcf86cd799439011");
+      expect.unreachable("expected loadDocOr404 to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIError);
+      const apiError = error as APIError;
+      expect(apiError.status).toBe(404);
+      expect(apiError.meta).toEqual({deleted: "true"});
+      expect(apiError.disableExternalErrorTracking).toBe(true);
+    }
+  });
+
+  it("rethrows APIError from query execution without wrapping", async () => {
+    const original = new APIError({status: 400, title: "validation failed"});
+    const model = {
+      collection: {findOne: mock(async () => null)},
+      findById: mock(() => ({
+        exec: mock(async () => {
+          throw original;
+        }),
+      })),
+      modelName: "MockModel",
+    } as any;
+
+    await expect(loadDocOr404(model, "507f1f77bcf86cd799439011")).rejects.toBe(original);
+  });
+
+  it("returns plain not found when document does not exist", async () => {
+    const model = {
+      collection: {findOne: mock(async () => null)},
+      findById: mock(() => ({exec: mock(async () => null)})),
+      modelName: "MockModel",
+    } as any;
+
+    try {
+      await loadDocOr404(model, "507f1f77bcf86cd799439011");
+      expect.unreachable("expected loadDocOr404 to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIError);
+      const apiError = error as APIError;
+      expect(apiError.status).toBe(404);
+      expect(apiError.meta).toBeUndefined();
+    }
+  });
+});

package/src/docLoader.ts

@@ -0,0 +1,77 @@
+import * as Sentry from "@sentry/bun";
+import mongoose, {type Model} from "mongoose";
+
+import {addPopulateToQuery} from "./api";
+import {APIError, isAPIError} from "./errors";
+import type {PopulatePath} from "./populate";
+
+/**
+ * Loads a document by id or throws a 404 APIError.
+ * Matches permission middleware behavior including soft-delete metadata.
+ */
+export const loadDocOr404 = async <T>(
+  model: Model<T>,
+  id: string,
+  populatePaths?: PopulatePath[]
+): Promise<T> => {
+  const builtQuery = model.findById(id);
+  const populatedQuery = addPopulateToQuery(
+    // biome-ignore lint/suspicious/noExplicitAny: Query types vary based on populate paths
+    builtQuery as any,
+    populatePaths
+  );
+  let data: T | null;
+  try {
+    data = (await populatedQuery.exec()) as T | null;
+  } catch (error: unknown) {
+    if (isAPIError(error)) {
+      throw error;
+    }
+    throw new APIError({
+      error: error as Error,
+      status: 500,
+      title: `GET failed on ${id}`,
+    });
+  }
+  if (!data) {
+    const hiddenDoc = await model.collection.findOne({
+      _id: new mongoose.Types.ObjectId(id),
+    });
+
+    if (!hiddenDoc) {
+      Sentry.captureMessage(`Document ${id} not found for model ${model.modelName}`);
+      const error = new APIError({
+        status: 404,
+        title: `Document ${id} not found for model ${model.modelName}`,
+      });
+      error.meta = undefined;
+      throw error;
+    }
+
+    let reason: {[key: string]: string} | null = null;
+    if (hiddenDoc.deleted) {
+      reason = {deleted: "true"};
+    } else if (hiddenDoc.disabled) {
+      reason = {disabled: "true"};
+    } else if (hiddenDoc.archived) {
+      reason = {archived: "true"};
+    }
+
+    if (!reason) {
+      const error = new APIError({
+        status: 404,
+        title: `Document ${id} not found for model ${model.modelName}`,
+      });
+      error.meta = undefined;
+      throw error;
+    }
+    throw new APIError({
+      disableExternalErrorTracking: true,
+      meta: reason,
+      status: 404,
+      title: `Document ${id} not found for model ${model.modelName}`,
+    });
+  }
+
+  return data;
+};

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./actions";
 export * from "./api";
 export * from "./auth";
 export * from "./betterAuth";
@@ -36,3 +37,4 @@ export * from "./types/consentForm";
 export * from "./types/consentResponse";
 export * from "./utils";
 export * from "./versionCheckPlugin";
+export {z} from "./zodOpenApi";

package/src/permissions.ts

@@ -1,10 +1,10 @@
-import * as Sentry from "@sentry/bun";
 import type express from "express";
 import type {NextFunction} from "express";
-import mongoose, {type Model} from "mongoose";
+import type {Model} from "mongoose";
 
-import {addPopulateToQuery, type ModelRouterOptions, type RESTMethod} from "./api";
+import type {ModelRouterOptions, RESTMethod} from "./api";
 import type {User} from "./auth";
+import {loadDocOr404} from "./docLoader";
 import {APIError} from "./errors";
 import {logger} from "./logger";
 
@@ -145,65 +145,7 @@ export const permissionMiddleware = <T>(
         return next();
       }
 
-      const builtQuery = model.findById(req.params.id);
-      const populatedQuery = addPopulateToQuery(
-        // biome-ignore lint/suspicious/noExplicitAny: Query types vary based on populate paths
-        builtQuery as any,
-        options.populatePaths
-      );
-      let data: T | null;
-      try {
-        data = (await populatedQuery.exec()) as T | null;
-      } catch (error: unknown) {
-        throw new APIError({
-          error: error as Error,
-          status: 500,
-          title: `GET failed on ${req.params.id}`,
-        });
-      }
-      if (!data) {
-        // Check if document exists but is hidden. Completely skip plugins.
-        const hiddenDoc = await model.collection.findOne({
-          _id: new mongoose.Types.ObjectId(req.params.id as string),
-        });
-
-        if (!hiddenDoc) {
-          Sentry.captureMessage(`Document ${req.params.id} not found for model ${model.modelName}`);
-          const error = new APIError({
-            status: 404,
-            title: `Document ${req.params.id} not found for model ${model.modelName}`,
-          });
-          error.meta = undefined;
-          throw error;
-        }
-
-        // Document exists but is hidden
-        let reason: {[key: string]: string} | null = 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) {
-          const error = new APIError({
-            status: 404,
-            title: `Document ${req.params.id} not found for model ${model.modelName}`,
-          });
-          error.meta = undefined;
-          throw error;
-        }
-        throw new APIError({
-          // We don't want to send this to Sentry because it's expected behavior.
-          disableExternalErrorTracking: true,
-          meta: reason,
-          status: 404,
-          title: `Document ${req.params.id} not found for model ${model.modelName}`,
-        });
-      }
+      const data = await loadDocOr404<T>(model, req.params.id as string, options.populatePaths);
 
       if (!(await checkPermissions(method, options.permissions[method], req.user, data))) {
         throw new APIError({

package/src/zodOpenApi.ts

@@ -0,0 +1,6 @@
+import {extendZodWithOpenApi} from "@asteasolutions/zod-to-openapi";
+import {z} from "zod";
+
+extendZodWithOpenApi(z);
+
+export {z};