@terreno/api 0.20.2 → 0.22.0

package/src/actions.openApi.test.ts

@@ -3,8 +3,6 @@ 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 {FoodModel, setupDb, UserModel} from "./tests";
@@ -57,6 +55,8 @@ const primeActionOpenApiRoutes = async (
 };
 
 const assertActionOpenApiSpec = (spec: Record<string, unknown>): void => {
+  expect(spec.requestId).toBeUndefined();
+
   const paths = spec.paths as Record<string, Record<string, unknown>>;
   const collectionPath = paths["/food/summarize"];
   const instancePath = paths["/food/{id}/ping"];
@@ -139,14 +139,18 @@ describe("action OpenAPI emission", () => {
 
       const specRes = await server.get("/openapi.json").expect(200);
       assertActionOpenApiSpec(specRes.body);
+
+      const pingRes = await server.get(`/food/${foodId}/ping`).expect(200);
+      expect(pingRes.body.data).toEqual({id: foodId});
+      expect(pingRes.body.requestId).toBe(pingRes.headers["x-request-id"]);
     });
   });
 
-  describe("setupServer", () => {
+  describe("configureApp", () => {
     let app: express.Application;
 
     beforeEach(() => {
-      const addRoutes = (
+      const configureApp = (
         router: express.Router,
         routerOptions?: Partial<ModelRouterOptions<unknown>>
       ): void => {
@@ -156,16 +160,14 @@ describe("action OpenAPI emission", () => {
         );
       };
 
-      app = setupServer({
-        addRoutes,
+      app = new TerrenoApp({
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
-      setupAuth(app, UserModel as any);
-      addAuthRoutes(app, UserModel as any);
+      }).build();
     });
 
-    it("emits the same action operations on first hit via legacy setupServer", async () => {
+    it("emits the same action operations on first hit via configureApp", async () => {
       const server = supertest(app);
       await primeActionOpenApiRoutes(server, foodId);
 

package/src/api.query.test.ts

@@ -95,7 +95,17 @@ describe("query and list methods", () => {
           update: [Permissions.IsOwner],
         },
         populatePaths: [{path: "ownerId"}],
-        queryFields: ["hidden", "name", "calories", "created", "source.name", "tags", "eatenBy"],
+        queryFields: [
+          "hidden",
+          "name",
+          "calories",
+          "created",
+          "created_gte",
+          "created_lte",
+          "source.name",
+          "tags",
+          "eatenBy",
+        ],
         sort: {created: "descending"},
       })
     );
@@ -190,6 +200,19 @@ describe("query and list methods", () => {
     expect(res.body.data[0].id).toBe((apple as any).id);
   });
 
+  it("list applies created_gte and created_lte as a Date range", async () => {
+    const res = await agent
+      .get("/food")
+      .query({
+        created_gte: "2021-12-03T00:00:05.000Z",
+        created_lte: "2021-12-03T00:00:25.000Z",
+        limit: 10,
+      })
+      .expect(200);
+    const names = (res.body.data as {name: string}[]).map((d) => d.name).sort();
+    expect(names).toEqual(["Pizza", "Spinach"]);
+  });
+
   it("list query params not in list", async () => {
     const res = await agent.get(`/food?ownerId=${admin._id}`).expect(400);
     expect(res.body.title).toBe("ownerId is not allowed as a query param.");

package/src/api.test.ts

@@ -2040,5 +2040,174 @@ describe("@terreno/api", () => {
 
       expect(res.body.data.name).toBe("Spinach");
     });
+
+    it("returns 400 when X-Unmodified-Since-ISO header is an invalid date", async () => {
+      const res = await agent
+        .patch(`/food/${spinach._id}`)
+        .set("X-Unmodified-Since-ISO", "not-a-date")
+        .send({name: "Bad Date"})
+        .expect(400);
+
+      expect(res.body.title).toBe("Invalid conflict-detection timestamp");
+      expect(res.body.detail).toContain("X-Unmodified-Since-ISO");
+    });
+
+    it("returns 400 when If-Unmodified-Since header is an invalid HTTP date", async () => {
+      const res = await agent
+        .patch(`/food/${spinach._id}`)
+        .set("If-Unmodified-Since", "not-a-valid-http-date")
+        .send({name: "Bad HTTP Date"})
+        .expect(400);
+
+      expect(res.body.title).toBe("Invalid conflict-detection timestamp");
+      expect(res.body.detail).toContain("If-Unmodified-Since");
+    });
+
+    it("returns 400 when _updatedAt body field is an invalid date", async () => {
+      const res = await agent
+        .patch(`/food/${spinach._id}`)
+        .send({_updatedAt: "garbage-date", name: "Bad Body Date"})
+        .expect(400);
+
+      expect(res.body.title).toBe("Invalid conflict-detection timestamp");
+      expect(res.body.detail).toContain("_updatedAt");
+    });
+
+    it("handles doc timestamp stored as ISO string", async () => {
+      await FoodModel.collection.updateOne(
+        {_id: spinach._id as unknown as mongoose.Types.ObjectId},
+        {$set: {updated: "2025-06-15T12:00:00.000Z"}}
+      );
+
+      const res = await agent
+        .patch(`/food/${spinach._id}`)
+        .set("If-Unmodified-Since", DateTime.fromISO("2025-06-15T11:00:00.000Z").toHTTP()!)
+        .send({name: "String Timestamp"})
+        .expect(409);
+
+      expect(res.body.error).toBe("Conflict");
+    });
+  });
+
+  describe("three-arg modelRouter registration", () => {
+    it("returns a ModelRouterRegistration with path and realtime", () => {
+      const registration = modelRouter("/food", FoodModel, {
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+        realtime: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      });
+      expect(registration).toHaveProperty("__type", "modelRouter");
+      expect(registration).toHaveProperty("path", "/food");
+      expect(registration).toHaveProperty("router");
+      expect(registration).toHaveProperty("_buildWithOpenApi");
+    });
+
+    it("logs a warning when realtime config is used without the path form", () => {
+      const router = modelRouter(FoodModel, {
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+        realtime: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      });
+      // Returns a plain Router, not a registration, because no path was given
+      expect(router).toBeDefined();
+      expect(router).not.toHaveProperty("__type");
+    });
+  });
+
+  describe("create transform error wrapping", () => {
+    let admin: mongoose.HydratedDocument<User>;
+    let agent: TestAgent;
+
+    beforeEach(async () => {
+      [admin] = await setupDb();
+
+      app = getBaseServer();
+      setupAuth(app, UserModel as unknown as Parameters<typeof setupAuth>[1]);
+      addAuthRoutes(app, UserModel as unknown as Parameters<typeof addAuthRoutes>[1]);
+      app.use(
+        "/food",
+        modelRouter(FoodModel, {
+          permissions: {
+            create: [Permissions.IsAny],
+            delete: [Permissions.IsAny],
+            list: [Permissions.IsAny],
+            read: [Permissions.IsAny],
+            update: [Permissions.IsAny],
+          },
+          transformer: {
+            transform: () => {
+              throw new Error("generic transform error");
+            },
+          },
+        })
+      );
+      server = supertest(app);
+      agent = await authAsUser(app, "admin");
+    });
+
+    it("wraps non-APIError transform errors in a 400 APIError on create", async () => {
+      const res = await agent
+        .post("/food")
+        .send({calories: 10, name: "New Food", ownerId: admin._id})
+        .expect(400);
+
+      expect(res.body.title).toContain("generic transform error");
+    });
+  });
+
+  describe("update transform error wrapping", () => {
+    let admin: mongoose.HydratedDocument<User>;
+    let agent: TestAgent;
+    let spinach: Food;
+
+    beforeEach(async () => {
+      [admin] = await setupDb();
+      spinach = await FoodModel.create({
+        calories: 10,
+        created: new Date(),
+        hidden: false,
+        name: "Spinach",
+        ownerId: admin._id,
+      });
+
+      app = getBaseServer();
+      setupAuth(app, UserModel as unknown as Parameters<typeof setupAuth>[1]);
+      addAuthRoutes(app, UserModel as unknown as Parameters<typeof addAuthRoutes>[1]);
+      app.use(
+        "/food",
+        modelRouter(FoodModel, {
+          permissions: {
+            create: [Permissions.IsAny],
+            delete: [Permissions.IsAny],
+            list: [Permissions.IsAny],
+            read: [Permissions.IsAny],
+            update: [Permissions.IsAny],
+          },
+          transformer: {
+            transform: () => {
+              throw new Error("update transform error");
+            },
+          },
+        })
+      );
+      server = supertest(app);
+      agent = await authAsUser(app, "admin");
+    });
+
+    it("wraps non-APIError transform errors in a 403 APIError on update", async () => {
+      const res = await agent.patch(`/food/${spinach._id}`).send({name: "Updated"}).expect(403);
+
+      expect(res.body.title).toContain("update transform error");
+    });
   });
 });

package/src/api.ts

@@ -342,6 +342,75 @@ export interface ModelRouterOptions<T> {
   realtime?: RealtimeConfig;
 }
 
+/**
+ * Parses a date-range query bound from an ISO-8601 string using Luxon, throwing a 400
+ * APIError when the value cannot be parsed. Centralizes date-string parsing so the repo's
+ * Luxon convention is honored for admin changelist date-range filters.
+ */
+const parseDateRangeBound = (rawValue: unknown, queryKey: string): Date => {
+  const parsed = DateTime.fromISO(String(rawValue), {zone: "utc"});
+  if (!parsed.isValid) {
+    throw new APIError({
+      status: 400,
+      title: `Invalid date for query parameter ${queryKey}`,
+    });
+  }
+  return parsed.toJSDate();
+};
+
+/**
+ * Collapses `field_gte` / `field_lte` query pairs into `{ field: { $gte, $lte } }` for Date paths,
+ * so admin changelist date-range filters map to valid Mongoose range queries.
+ */
+const mergeDateRangeQueryParams = <T>(
+  model: Model<T>,
+  query: Record<string, unknown>
+): Record<string, unknown> => {
+  const schema = model.schema;
+  const result: Record<string, unknown> = {...query};
+  const dateRangeBases = new Set<string>();
+  for (const key of Object.keys(result)) {
+    const match = /^(.+)_(gte|lte)$/.exec(key);
+    if (!match) {
+      continue;
+    }
+    const baseField = match[1];
+    const path = schema.path(baseField);
+    if (!path || path.instance !== "Date") {
+      continue;
+    }
+    dateRangeBases.add(baseField);
+  }
+  for (const baseField of dateRangeBases) {
+    const gteKey = `${baseField}_gte`;
+    const lteKey = `${baseField}_lte`;
+    const gteRaw = result[gteKey];
+    const lteRaw = result[lteKey];
+    const bounds: {$gte?: Date; $lte?: Date} = {};
+    if (gteRaw !== undefined && gteRaw !== null && String(gteRaw).trim() !== "") {
+      bounds.$gte = parseDateRangeBound(gteRaw, gteKey);
+    }
+    if (lteRaw !== undefined && lteRaw !== null && String(lteRaw).trim() !== "") {
+      bounds.$lte = parseDateRangeBound(lteRaw, lteKey);
+    }
+    if (Object.keys(bounds).length === 0) {
+      continue;
+    }
+    delete result[gteKey];
+    delete result[lteKey];
+    const direct = result[baseField];
+    if (direct !== undefined && direct !== null && typeof direct !== "object") {
+      delete result[baseField];
+    }
+    if (typeof direct === "object" && direct !== null && !Array.isArray(direct)) {
+      result[baseField] = {...(direct as Record<string, unknown>), ...bounds};
+    } else {
+      result[baseField] = bounds;
+    }
+  }
+  return result;
+};
+
 // Ensures query params are allowed. Also checks nested query params when using $and/$or.
 const checkQueryParamAllowed = (
   queryParam: string,
@@ -711,6 +780,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
         }
       }
 
+      query = mergeDateRangeQueryParams(model, query);
+
       // Special operators. NOTE: these request Mongo Atlas.
       if (req.query.$search) {
         mongoose.connection.db?.collection(model.collection.collectionName);