fix: remove unused types and simplify request body parsing in endpoints

Author: NoOne7135

endpoints/context.ts

@@ -4,7 +4,6 @@ import type {
   ChatSurfaceIncomingMessage,
   IAdminForth,
 } from "adminforth";
-import type { ZodType } from "zod";
 import type {
   HandleSpeechTurnInput,
   HandleTurnInput,
@@ -13,10 +12,6 @@ import type {
 } from "../agentTurnService.js";
 import type { PluginOptions } from "../types.js";
 
-export type EndpointResponse = {
-  setStatus: (code: number, message: string) => void;
-};
-
 export type SessionTurn = {
   prompt: string;
   response: string;
@@ -25,7 +20,6 @@ export type SessionTurn = {
 export type AgentEndpointsContext = {
   adminforth: IAdminForth;
   options: PluginOptions;
-  parseBody<T>(schema: ZodType<T>, body: unknown, response: EndpointResponse): T | null;
   handleTurn(input: HandleTurnInput): Promise<RunAndPersistAgentResponseResult>;
   handleSpeechTurn(input: HandleSpeechTurnInput): Promise<RunAndPersistAgentResponseResult | null>;
   runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput): Promise<RunAndPersistAgentResponseResult>;
@@ -41,12 +35,12 @@ export type AgentEndpointsContext = {
 
 export type CoreEndpointsContext = Pick<
   AgentEndpointsContext,
-  "options" | "parseBody" | "handleTurn" | "handleSpeechTurn"
+  "options" | "handleTurn" | "handleSpeechTurn"
 >;
 
 export type SessionEndpointsContext = Pick<
   AgentEndpointsContext,
-  "adminforth" | "options" | "parseBody" | "getSessionTurns" | "createNewTurn"
+  "adminforth" | "options" | "getSessionTurns" | "createNewTurn"
   | "createSystemTurn"
 >;
 

endpoints/core.ts

@@ -12,20 +12,53 @@ type MulterFile = {
 
 type ExpressMulterRequest = { file?: MulterFile };
 
+const currentPageContextSchema = z.object({
+  path: z.string(),
+  fullPath: z.string(),
+  title: z.string(),
+  url: z.string(),
+}).strict() satisfies z.ZodType<CurrentPageContext>;
+
 const agentResponseBodySchema = z.object({
   message: z.string(),
   sessionId: z.string(),
   mode: z.string().nullish(),
   timeZone: z.string().optional(),
-  currentPage: z.custom<CurrentPageContext>().optional(),
+  currentPage: currentPageContextSchema.optional(),
 }).strict();
 
 const agentApprovalBodySchema = z.object({
   sessionId: z.string(),
   decision: z.enum(["approve", "reject"]),
 }).strict();
 
-const agentSpeechResponseBodySchema = agentResponseBodySchema.omit({ message: true });
+// Sent as multipart/form-data (via multer), so every field arrives as a plain string on the wire.
+// `currentPage` is JSON.stringify'd by the client into a form field and must be parsed back into
+// an object. Zod -> JSON-Schema conversion cannot represent `.transform()` at all (it throws), so
+// `agentSpeechResponseShapeSchema` (plain strings, no transform) is what's passed as request_schema
+// for the AJV pre-check, while `agentSpeechResponseBodySchema` (with the transform) is used via an
+// inline safeParse in the handler to actually parse `currentPage` into an object.
+const agentSpeechResponseShapeSchema = z.object({
+  sessionId: z.string(),
+  mode: z.string().nullish(),
+  timeZone: z.string().optional(),
+  currentPage: z.string().optional(),
+}).strict();
+
+const agentSpeechResponseBodySchema = agentSpeechResponseShapeSchema.extend({
+  currentPage: z.string().optional().transform((value, ctx) => {
+    if (value === undefined) return undefined;
+    try {
+      return currentPageContextSchema.parse(JSON.parse(value));
+    } catch (err) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `currentPage must be a JSON-encoded object matching CurrentPageContext: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      return z.NEVER;
+    }
+  }),
+});
 
 export function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServer) {
   server.endpoint({
@@ -52,9 +85,9 @@ export function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServe
   server.endpoint({
     method: 'POST',
     path: `/agent/response`,
+    request_schema: agentResponseBodySchema,
     handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
-      const data = ctx.parseBody(agentResponseBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof agentResponseBodySchema>;
       const emit = createSseEventEmitter(_raw_express_res, {
         vercelAiUiMessageStream: true,
         closeActiveBlockOnToolStart: true,
@@ -79,9 +112,9 @@ export function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServe
   server.endpoint({
     method: 'POST',
     path: `/agent/approval`,
+    request_schema: agentApprovalBodySchema,
     handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
-      const data = ctx.parseBody(agentApprovalBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof agentApprovalBodySchema>;
       const emit = createSseEventEmitter(_raw_express_res, {
         vercelAiUiMessageStream: true,
         closeActiveBlockOnToolStart: true,
@@ -105,15 +138,20 @@ export function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServe
     method: 'POST',
     path: `/agent/speech-response`,
     target: 'upload',
+    request_schema: agentSpeechResponseShapeSchema,
     handler: async ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) => {
       const req = _raw_express_req as ExpressMulterRequest;
       const audioAdapter = ctx.options.audioAdapter;
       if (!audioAdapter) {
         response.setStatus(400, "Audio adapter is not configured for AdminForth Agent");
         return { error: "Audio adapter is not configured for AdminForth Agent" };
       }
-      const data = ctx.parseBody(agentSpeechResponseBodySchema, body, response);
-      if (!data) return;
+      const parsed = agentSpeechResponseBodySchema.safeParse(body);
+      if (!parsed.success) {
+        response.setStatus(400, 'Request body validation failed');
+        return { error: 'Request body validation failed', details: parsed.error.issues };
+      }
+      const data = parsed.data;
       if (!req.file) {
         response.setStatus(400, "Audio file is required");
         return { error: "Audio file is required" };

endpoints/sessions.ts

@@ -26,9 +26,9 @@ export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHtt
   server.endpoint({
     method: 'POST',
     path: `/agent/get-sessions`,
+    request_schema: getSessionsBodySchema,
     handler: async ({body, adminUser, response }) => {
-      const data = ctx.parseBody(getSessionsBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof getSessionsBodySchema>;
       const userId = adminUser!.pk;
       const limit = data.limit ?? 20;
       const sessions = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).list(
@@ -47,9 +47,9 @@ export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHtt
   server.endpoint({
     method: 'POST',
     path: `/agent/get-session-info`,
+    request_schema: sessionIdBodySchema,
     handler: async ({body, adminUser, response }) => {
-      const data = ctx.parseBody(sessionIdBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof sessionIdBodySchema>;
       const userId = adminUser!.pk;
       const sessionId = data.sessionId;
       const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
@@ -102,9 +102,9 @@ export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHtt
   server.endpoint({
     method: 'POST',
     path: `/agent/create-session`,
+    request_schema: createSessionBodySchema,
     handler: async ({body, adminUser, response }) => {
-      const data = ctx.parseBody(createSessionBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof createSessionBodySchema>;
       const triggerMessage = data.triggerMessage;
       const userId = adminUser!.pk;
       const title = triggerMessage?.slice(0, 40) || "New Session";
@@ -126,9 +126,9 @@ export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHtt
   server.endpoint({
     method: 'POST',
     path: `/agent/delete-session`,
+    request_schema: sessionIdBodySchema,
     handler: async ({body, adminUser, response }) => {
-      const data = ctx.parseBody(sessionIdBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof sessionIdBodySchema>;
       const sessionId = data.sessionId;
       const userId = adminUser!.pk;
       const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
@@ -158,9 +158,9 @@ export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHtt
   server.endpoint({
     method: 'POST',
     path: `/agent/add-system-message-to-turns`,
+    request_schema: addSystemMessageBodySchema,
     handler: async ({body, adminUser, response }) => {
-      const data = ctx.parseBody(addSystemMessageBodySchema, body, response);
-      if (!data) return;
+      const data = body as z.infer<typeof addSystemMessageBodySchema>;
       const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
         [Filters.EQ(ctx.options.sessionResource.idField, data.sessionId)]
       );

index.ts

@@ -8,7 +8,6 @@ import { AdminForthPlugin } from "adminforth";
 
 import type { PluginOptions } from './types.js';
 import { MemorySaver, type BaseCheckpointSaver } from "@langchain/langgraph";
-import { z } from "zod";
 import { AdminForthCheckpointSaver } from "./agent/checkpointer.js";
 import { appendCustomSystemPrompt, buildAgentSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT} from "./agent/systemPrompt.js";
 import { setupCoreEndpoints } from "./endpoints/core.js";
@@ -41,18 +40,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
   private agentTurnService: AgentTurnService;
   private speechTurnService: SpeechTurnService;
   private chatSurfaceService: ChatSurfaceService;
-  private parseBody<T>(
-    schema: z.ZodType<T>,
-    body: unknown,
-    response: { setStatus: (code: number, message: string) => void },
-  ): T | null {
-    const parsed = schema.safeParse(body ?? {});
-    if (!parsed.success) {
-      response.setStatus(422, parsed.error.message);
-      return null;
-    }
-    return parsed.data;
-  }
   private getCheckpointer() {
     if (this.checkpointer) return this.checkpointer;
 
@@ -189,7 +176,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     const endpointContext = {
       adminforth: this.adminforth,
       options: this.options,
-      parseBody: this.parseBody.bind(this),
       handleTurn: this.agentTurnService.handleTurn.bind(this.agentTurnService),
       handleSpeechTurn: this.speechTurnService.handle.bind(this.speechTurnService),
       runAndPersistAgentResponse: this.agentTurnService.runAndPersistAgentResponse.bind(this.agentTurnService),

package.json

@@ -25,7 +25,7 @@
   "description": "AI agent plugin for AdminForth with tool-based workflows and persistent chat sessions",
   "devDependencies": {
     "@types/node": "latest",
-    "adminforth": "^3.7.1",
+    "adminforth": "^3.8.2",
     "semantic-release": "^24.2.1",
     "semantic-release-slack-bot": "^4.0.2",
     "typescript": "^5.7.3"
@@ -67,6 +67,6 @@
     }
   ],
   "peerDependencies": {
-    "adminforth": "^3.7.1"
+    "adminforth": "^3.8.2"
   }
 }