feat(audit): add pagination response envelope

src/__tests__/routes/audit.test.ts

@@ -32,7 +32,7 @@ describe("auditRouter", () => {
         .set("Origin", allowedOrigin);
 
       expect(response.status).toBe(200);
-      expect(response.body).toEqual({ events: [] });
+      expect(response.body).toEqual({ items: [], next_cursor: null });
     });
 
     it("accepts a valid limit query parameter", async () => {
@@ -41,7 +41,16 @@ describe("auditRouter", () => {
         .set("Origin", allowedOrigin);
 
       expect(response.status).toBe(200);
-      expect(response.body).toEqual({ events: [] });
+      expect(response.body).toEqual({ items: [], next_cursor: null });
+
+    it("keeps the envelope stable when a cursor is provided", async () => {
+      const response = await request(app)
+        .get("/api/audit?limit=5&cursor=opaque-cursor")
+        .set("Origin", allowedOrigin);
+
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual({ items: [], next_cursor: null });
+    });
     });
 
     it("returns 400 if limit is not a number", async () => {

src/routes/audit.ts

@@ -21,6 +21,11 @@ auditRouter.use(accessLog);
  *       - Audit
  *     parameters:
  *       - in: query
+ *         name: cursor
+ *         schema:
+ *           type: string
+ *         description: Opaque cursor for the next page
+ *       - in: query
  *         name: limit
  *         schema:
  *           type: integer
@@ -30,16 +35,19 @@ auditRouter.use(accessLog);
  *         description: Maximum number of events to return
  *     responses:
  *       200:
- *         description: A list of audit events
+ *         description: A cursor-paginated page of audit events
  *         content:
  *           application/json:
  *             schema:
  *               type: object
  *               properties:
- *                 events:
+ *                 items:
  *                   type: array
  *                   items:
  *                     type: object
+ *                 next_cursor:
+ *                   type: string
+ *                   nullable: true
  *       400:
  *         description: Invalid input
  *         content:
@@ -56,6 +64,7 @@ auditRouter.get("/", (req, res) => {
     return;
   }
 
-  // Placeholder for real audit events
-  res.json({ events: [] });
+  // Placeholder for real audit events. Keep the pagination envelope stable
+  // while the backing audit store is introduced.
+  res.json({ items: [], next_cursor: null });
 });