feat: implement standardized API response handling and utilities

Author: Marvin Zhang

packages/mcp/src/api/devlog-api-client.ts

@@ -106,6 +106,19 @@ export class DevlogApiClient {
     }
   }
 
+  /**
+   * Unwrap standardized API response
+   */
+  private unwrapApiResponse<T>(response: any): T {
+    // Handle standardized API response format
+    if (response && response.success === true) {
+      return response.data;
+    }
+
+    // Handle legacy direct response (during transition)
+    return response;
+  }
+
   /**
    * GET request helper
    */
@@ -154,33 +167,40 @@ export class DevlogApiClient {
 
   // Project Management
   async listProjects(): Promise<any[]> {
-    return this.get('/api/projects');
+    const response = await this.get('/api/projects');
+    return this.unwrapApiResponse<any[]>(response);
   }
 
   async getProject(projectId?: number): Promise<any> {
     const id = projectId || this.currentProjectId || 0;
-    return this.get(`/api/projects/${id}`);
+    const response = await this.get(`/api/projects/${id}`);
+    return this.unwrapApiResponse<any>(response);
   }
 
   async createProject(data: any): Promise<any> {
-    return this.post('/api/projects', data);
+    const response = await this.post('/api/projects', data);
+    return this.unwrapApiResponse<any>(response);
   }
 
   // Devlog Operations
   async createDevlog(data: CreateDevlogRequest): Promise<DevlogEntry> {
-    return this.post(`${this.getProjectEndpoint()}/devlogs`, data);
+    const response = await this.post(`${this.getProjectEndpoint()}/devlogs`, data);
+    return this.unwrapApiResponse<DevlogEntry>(response);
   }
 
   async getDevlog(id: number): Promise<DevlogEntry> {
-    return this.get(`${this.getProjectEndpoint()}/devlogs/${id}`);
+    const response = await this.get(`${this.getProjectEndpoint()}/devlogs/${id}`);
+    return this.unwrapApiResponse<DevlogEntry>(response);
   }
 
   async updateDevlog(id: number, data: UpdateDevlogRequest): Promise<DevlogEntry> {
-    return this.put(`${this.getProjectEndpoint()}/devlogs/${id}`, data);
+    const response = await this.put(`${this.getProjectEndpoint()}/devlogs/${id}`, data);
+    return this.unwrapApiResponse<DevlogEntry>(response);
   }
 
   async deleteDevlog(id: number): Promise<void> {
-    return this.delete(`${this.getProjectEndpoint()}/devlogs/${id}`);
+    const response = await this.delete(`${this.getProjectEndpoint()}/devlogs/${id}`);
+    return this.unwrapApiResponse<void>(response);
   }
 
   async listDevlogs(filter?: DevlogFilter): Promise<PaginatedResult<DevlogEntry>> {
@@ -198,7 +218,8 @@ export class DevlogApiClient {
     }
 
     const query = params.toString() ? `?${params.toString()}` : '';
-    return this.get(`${this.getProjectEndpoint()}/devlogs${query}`);
+    const response = await this.get(`${this.getProjectEndpoint()}/devlogs${query}`);
+    return this.unwrapApiResponse<PaginatedResult<DevlogEntry>>(response);
   }
 
   async searchDevlogs(query: string, filter?: DevlogFilter): Promise<PaginatedResult<DevlogEntry>> {
@@ -211,7 +232,10 @@ export class DevlogApiClient {
       if (filter.archived !== undefined) params.append('archived', String(filter.archived));
     }
 
-    return this.get(`${this.getProjectEndpoint()}/devlogs/search?${params.toString()}`);
+    const response = await this.get(
+      `${this.getProjectEndpoint()}/devlogs/search?${params.toString()}`,
+    );
+    return this.unwrapApiResponse<PaginatedResult<DevlogEntry>>(response);
   }
 
   async addDevlogNote(
@@ -221,24 +245,28 @@ export class DevlogApiClient {
     files?: string[],
     codeChanges?: string,
   ): Promise<DevlogEntry> {
-    return this.post(`${this.getProjectEndpoint()}/devlogs/${devlogId}/notes`, {
+    const response = await this.post(`${this.getProjectEndpoint()}/devlogs/${devlogId}/notes`, {
       note,
       category,
       files,
       codeChanges,
     });
+    return this.unwrapApiResponse<DevlogEntry>(response);
   }
 
   async archiveDevlog(id: number): Promise<DevlogEntry> {
-    return this.put(`${this.getProjectEndpoint()}/devlogs/${id}/archive`, {});
+    const response = await this.put(`${this.getProjectEndpoint()}/devlogs/${id}/archive`, {});
+    return this.unwrapApiResponse<DevlogEntry>(response);
   }
 
   async unarchiveDevlog(id: number): Promise<DevlogEntry> {
-    return this.put(`${this.getProjectEndpoint()}/devlogs/${id}/unarchive`, {});
+    const response = await this.put(`${this.getProjectEndpoint()}/devlogs/${id}/unarchive`, {});
+    return this.unwrapApiResponse<DevlogEntry>(response);
   }
 
   // Health check
   async healthCheck(): Promise<{ status: string; timestamp: string }> {
-    return this.get('/api/health');
+    const response = await this.get('/api/health');
+    return this.unwrapApiResponse<{ status: string; timestamp: string }>(response);
   }
 }

packages/mcp/src/tools/project-tools.ts

@@ -78,6 +78,7 @@ export async function handleGetCurrentProject(adapter: any) {
   try {
     const currentProjectId = adapter.getCurrentProjectId();
     const projects = await adapter.apiClient.listProjects();
+    // Both should be numbers now
     const currentProject = projects.find((p: any) => p.id === currentProjectId);
 
     if (!currentProject) {
@@ -96,7 +97,7 @@ export async function handleGetCurrentProject(adapter: any) {
 ID: ${currentProject.id}
 Description: ${currentProject.description || 'No description'}
 Created: ${new Date(currentProject.createdAt).toLocaleDateString()}
-Updated: ${new Date(currentProject.lastAccessedAt).toLocaleDateString()}
+Updated: ${new Date(currentProject.updatedAt).toLocaleDateString()}
 
 Note: This is the MCP server's in-memory current project. Web app project may differ.`;
 
@@ -123,9 +124,23 @@ Note: This is the MCP server's in-memory current project. Web app project may di
 
 export async function handleSwitchProject(adapter: any, args: { projectId: string }) {
   try {
+    // Convert string argument to number for consistency
+    const targetProjectId = parseInt(args.projectId, 10);
+    if (isNaN(targetProjectId)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid project ID '${args.projectId}'. Must be a valid number.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
     // Validate that the project exists
     const projects = await adapter.apiClient.listProjects();
-    const targetProject = projects.find((p: any) => p.id === args.projectId);
+    const targetProject = projects.find((p: any) => p.id === targetProjectId);
 
     if (!targetProject) {
       return {
@@ -140,13 +155,13 @@ export async function handleSwitchProject(adapter: any, args: { projectId: strin
     }
 
     // Switch current project in memory only
-    adapter.setCurrentProjectId(args.projectId);
+    adapter.setCurrentProjectId(targetProjectId);
 
     const switchInfo = `Successfully switched MCP server to project: **${targetProject.name}**
 ID: ${targetProject.id}
 Description: ${targetProject.description || 'No description'}
 Created: ${new Date(targetProject.createdAt).toLocaleDateString()}
-Updated: ${new Date(targetProject.lastAccessedAt).toLocaleDateString()}
+Updated: ${new Date(targetProject.updatedAt).toLocaleDateString()}
 
 Note: This only affects the MCP server's current project. Web app project is managed separately.`;
 

packages/web/app/api/projects/route.ts

@@ -1,6 +1,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ProjectService } from '@codervisor/devlog-core';
 import { ApiValidator, CreateProjectBodySchema, WebToServiceProjectCreateSchema } from '@/schemas';
+import {
+  createSimpleCollectionResponse,
+  createSuccessResponse,
+  ResponseTransformer,
+} from '@/utils/api-responses';
 
 // Mark this route as dynamic to prevent static generation
 export const dynamic = 'force-dynamic';
@@ -12,18 +17,12 @@ export async function GET(request: NextRequest) {
     await projectService.initialize();
 
     const coreProjects = await projectService.list();
-    
+
     // Transform core project data to web interface format
-    const projects = coreProjects.map(project => ({
-      id: project.id.toString(), // Convert number to string
-      name: project.name,
-      description: project.description,
-      tags: [], // Add empty tags array for compatibility
-      createdAt: project.createdAt.toISOString(), // Convert Date to string
-      updatedAt: project.lastAccessedAt.toISOString(), // Map lastAccessedAt to updatedAt
-    }));
+    const projects = ResponseTransformer.transformProjects(coreProjects);
 
-    return NextResponse.json({ projects });
+    // Return new standardized format
+    return createSimpleCollectionResponse(projects);
   } catch (error) {
     console.error('Error fetching projects:', error);
     return ApiValidator.handleServiceError(error);
@@ -41,8 +40,8 @@ export async function POST(request: NextRequest) {
 
     // Transform to service layer type (with additional validation)
     const serviceData = ApiValidator.transformForService(
-      bodyValidation.data, 
-      WebToServiceProjectCreateSchema
+      bodyValidation.data,
+      WebToServiceProjectCreateSchema,
     );
 
     const projectService = ProjectService.getInstance();
@@ -52,16 +51,9 @@ export async function POST(request: NextRequest) {
     const coreProject = await projectService.create(serviceData);
 
     // Transform core project data to web interface format
-    const createdProject = {
-      id: coreProject.id.toString(), // Convert number to string
-      name: coreProject.name,
-      description: coreProject.description,
-      tags: [], // Add empty tags array for compatibility
-      createdAt: coreProject.createdAt.toISOString(), // Convert Date to string
-      updatedAt: coreProject.lastAccessedAt.toISOString(), // Map lastAccessedAt to updatedAt
-    };
+    const createdProject = ResponseTransformer.transformProject(coreProject);
 
-    return NextResponse.json(createdProject, { status: 201 });
+    return createSuccessResponse(createdProject, { status: 201 });
   } catch (error) {
     console.error('Error creating project:', error);
     return ApiValidator.handleServiceError(error);

packages/web/app/components/layout/NavigationSidebar.tsx

@@ -13,17 +13,8 @@ import {
   SidebarMenuButton,
   SidebarMenuItem,
   SidebarTrigger,
-  useSidebar,
 } from '@/components/ui/sidebar';
-import { Button } from '@/components/ui/button';
-import {
-  AppWindowIcon,
-  LayoutDashboardIcon,
-  FileTextIcon,
-  PlusIcon,
-  PanelRightClose,
-  PanelRightOpen,
-} from 'lucide-react';
+import { AppWindowIcon, LayoutDashboardIcon, FileTextIcon, PlusIcon } from 'lucide-react';
 
 interface NavigationSidebarProps {
   // No props needed - using built-in sidebar state
@@ -34,7 +25,6 @@ export function NavigationSidebar(_props: NavigationSidebarProps) {
   const pathname = usePathname();
   const [mounted, setMounted] = useState(false);
   const { currentProject } = useProject();
-  const { state } = useSidebar();
 
   // Handle client-side hydration
   useEffect(() => {
@@ -226,10 +216,8 @@ export function NavigationSidebar(_props: NavigationSidebarProps) {
         </SidebarMenu>
       </SidebarContent>
 
-      <SidebarFooter className="p-4">
-        <SidebarTrigger className="h-8 w-8 p-0 justify-center">
-          {state === 'collapsed' ? <PanelRightOpen size={16} /> : <PanelRightClose size={16} />}
-        </SidebarTrigger>
+      <SidebarFooter className="p-4 bg-background border-t-0">
+        <SidebarTrigger className="h-8 w-8 p-0" />
       </SidebarFooter>
     </Sidebar>
   );

packages/web/app/schemas/index.ts

@@ -1,6 +1,6 @@
 /**
  * Centralized schema exports for web API validation
- * 
+ *
  * This module provides a single entry point for all validation schemas
  * used across the web application's API endpoints.
  */
@@ -10,6 +10,7 @@ export * from './project';
 export * from './devlog';
 export * from './validation';
 export * from './bridge';
+export * from './responses';
 
 // Common schemas that might be used across multiple endpoints
 import { z } from 'zod';