managing-apps/.cursor/commands/implement-api-changes.md

# implement-api-changes

## When to Use

Use this command when:
- `ManagingApi.ts` has been updated (regenerated from backend)
- New API endpoints or types have been added to the backend
- You need to implement frontend features that use the new API changes

## Prerequisites

- Git repository initialized
- `ManagingApi.ts` file exists at `src/Managing.WebApp/src/generated/ManagingApi.ts`
- Backend API is running and accessible
- Frontend project structure is intact

## Execution Steps

### Step 1: Check if ManagingApi.ts Has Changed

Check git status for changes to ManagingApi.ts:

Run: `git status --short src/Managing.WebApp/src/generated/ManagingApi.ts`

**If file is modified:**
- Continue to Step 2

**If file is not modified:**
- Check if file exists: `test -f src/Managing.WebApp/src/generated/ManagingApi.ts`
- If missing: Error "ManagingApi.ts not found. Please regenerate it first."
- If exists but not modified: Inform "No changes detected in ManagingApi.ts. Nothing to implement."
- **STOP**: No changes to process

### Step 2: Analyze Git Changes

Get the diff to see what was added/changed:

Run: `git diff HEAD src/Managing.WebApp/src/generated/ManagingApi.ts`

**Analyze the diff to identify:**
- New client classes (e.g., `export class JobClient`)
- New methods in existing clients (e.g., `backtest_NewMethod()`)
- New interfaces/types (e.g., `export interface NewType`)
- New enums (e.g., `export enum NewEnum`)
- Modified existing types/interfaces

**Extract key information:**
- Client class names (e.g., `JobClient`, `BacktestClient`)
- Method names and signatures (e.g., `job_GetJobs(page: number, pageSize: number)`)
- Request/Response types (e.g., `PaginatedJobsResponse`, `JobStatus`)
- HTTP methods (GET, POST, PUT, DELETE)

### Step 3: Determine Frontend Implementation Needs

Based on the changes, determine what needs to be implemented:

**For new client classes:**
- Create or update hooks/services to use the new client
- Identify which pages/components should use the new API
- Determine data fetching patterns (useQuery, useMutation)

**For new methods in existing clients:**
- Find existing components using that client
- Determine if new UI components are needed
- Check if existing components need updates

**For new types/interfaces:**
- Identify where these types should be used
- Check if new form components are needed
- Determine if existing components need type updates

**Common patterns to look for:**
- `*Client` classes → Create hooks in `src/Managing.WebApp/src/hooks/`
- `Get*` methods → Use `useQuery` for data fetching
- `Post*`, `Put*`, `Delete*` methods → Use `useMutation` for mutations
- `Paginated*` responses → Create paginated table components
- `*Request` types → Create form components

### Step 4: Search Existing Frontend Code

Search for related code to understand context:

**For new client classes:**
- Search: `grep -r "Client" src/Managing.WebApp/src --include="*.tsx" --include="*.ts" | grep -i "similar"`
- Look for similar client usage patterns
- Find related pages/components

**For new methods:**
- Search: `grep -r "ClientName" src/Managing.WebApp/src --include="*.tsx" --include="*.ts"`
- Find where the client is already used
- Check existing patterns

**For new types:**
- Search: `grep -r "TypeName" src/Managing.WebApp/src --include="*.tsx" --include="*.ts"`
- Find if type is referenced anywhere
- Check related components

### Step 5: Implement Frontend Features

Based on analysis, implement the frontend code:

#### 5.1: Create/Update API Hooks

**For new client classes:**
- Create hook file: `src/Managing.WebApp/src/hooks/use[ClientName].tsx`
- Pattern:
```typescript
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { [ClientName] } from '../generated/ManagingApi'
import { useApiUrlStore } from '../app/store/apiUrlStore'

export const use[ClientName] = () => {
  const { apiUrl } = useApiUrlStore()
  const queryClient = useQueryClient()
  const client = new [ClientName]({}, apiUrl)
  
  // Add useQuery hooks for GET methods
  // Add useMutation hooks for POST/PUT/DELETE methods
  
  return { /* hooks */ }
}
```

**For new methods in existing clients:**
- Update existing hook file
- Add new useQuery/useMutation hooks following existing patterns

#### 5.2: Create/Update Components

**For GET methods (data fetching):**
- Create components that use `useQuery` with the new hook
- Follow existing component patterns (e.g., tables, lists, detail views)
- Use TypeScript types from ManagingApi.ts

**For POST/PUT/DELETE methods (mutations):**
- Create form components or action buttons
- Use `useMutation` with proper error handling
- Show success/error toasts
- Invalidate relevant queries after mutations

**For paginated responses:**
- Create paginated table components
- Use existing pagination patterns from the codebase
- Include sorting, filtering if supported

#### 5.3: Create/Update Pages

**If new major feature:**
- Create new page in `src/Managing.WebApp/src/pages/`
- Add routing if needed
- Follow existing page structure patterns

**If extending existing feature:**
- Update existing page component
- Add new sections/components as needed

#### 5.4: Update Types and Interfaces

**If new types are needed:**
- Import types from ManagingApi.ts
- Use types in component props/interfaces
- Ensure type safety throughout

### Step 6: Follow Frontend Patterns

**Always follow these patterns:**

1. **API Client Usage:**
   - Get `apiUrl` from `useApiUrlStore()`
   - Create client: `new ClientName({}, apiUrl)`
   - Use in hooks, not directly in components

2. **Data Fetching:**
   - Use `useQuery` from `@tanstack/react-query`
   - Set proper `queryKey` for caching
   - Handle loading/error states

3. **Mutations:**
   - Use `useMutation` from `@tanstack/react-query`
   - Invalidate related queries after success
   - Show user-friendly error messages

4. **Component Structure:**
   - Use functional components with TypeScript
   - Place static content at file end
   - Use DaisyUI/Tailwind for styling
   - Wrap in Suspense with fallback

5. **Error Handling:**
   - Catch errors in services/hooks
   - Return user-friendly error messages
   - Use error boundaries for unexpected errors

### Step 7: Verify Implementation

**Check for:**
- TypeScript compilation errors: `cd src/Managing.WebApp && npm run type-check` (if available)
- Import errors: All imports resolve correctly
- Type safety: All types from ManagingApi.ts are used correctly
- Pattern consistency: Follows existing codebase patterns

**If errors found:**
- Fix TypeScript errors
- Fix import paths
- Ensure types match API definitions
- **STOP** if critical errors cannot be resolved

### Step 8: Test Integration Points

**Verify:**
- API client is instantiated correctly
- Query keys are unique and appropriate
- Mutations invalidate correct queries
- Error handling works properly
- Loading states are handled

## Error Handling

**If ManagingApi.ts doesn't exist:**
- Check path: `src/Managing.WebApp/src/generated/ManagingApi.ts`
- If missing: Inform user to regenerate using NSwag
- Suggest: Run backend API, then `cd src/Managing.Nswag && dotnet build`

**If git diff is empty:**
- Check if file is staged: `git diff --cached`
- Check if file is untracked: `git status`
- If untracked: Use `git diff /dev/null src/Managing.WebApp/src/generated/ManagingApi.ts`

**If cannot determine changes:**
- Show the diff output to user
- Ask user to clarify what needs to be implemented
- Proceed with manual implementation guidance

**If frontend patterns unclear:**
- Search for similar implementations in codebase
- Follow closest matching pattern
- Ask user for clarification if needed

**If TypeScript errors:**
- Check type definitions in ManagingApi.ts
- Ensure imports are correct
- Verify types match API response structure
- Fix type mismatches

## Example Execution

**User input:** `/implement-api-changes`

**AI execution:**

1. Check changes: `git status --short src/Managing.WebApp/src/generated/ManagingApi.ts` → Modified
2. Analyze diff: `git diff HEAD src/Managing.WebApp/src/generated/ManagingApi.ts`
   - Found: New `JobClient` class
   - Found: Methods: `job_GetJobs()`, `job_GetJobStatus()`, `job_CancelJob()`
   - Found: Types: `PaginatedJobsResponse`, `BacktestJobStatusResponse`, `JobStatus` enum
3. Determine needs:
   - Create `useJobClient` hook
   - Create jobs list page/component
   - Create job status component
   - Add cancel job functionality
4. Search existing code:
   - Found similar pattern: `useBacktestClient` hook
   - Found similar page: `backtestPage` structure
5. Implement:
   - Create `src/Managing.WebApp/src/hooks/useJobClient.tsx`
   - Create `src/Managing.WebApp/src/pages/jobsPage/jobs.tsx`
   - Create `src/Managing.WebApp/src/components/mollecules/JobStatusCard.tsx`
   - Update routing if needed
6. Verify: Check TypeScript errors, imports, types
7. Success: "✅ Frontend implementation completed for Job API changes"

**If new method in existing client:**

1-2. Same as above
3. Found: New method `backtest_GetJobStatus(jobId: string)` in `BacktestClient`
4. Search: Found `BacktestClient` used in `backtestPage`
5. Implement:
   - Update existing `useBacktestClient` hook
   - Add job status display to backtest page
   - Add polling for job status updates
6. Verify and complete

## Important Notes

- ✅ **Always use TanStack Query** - Never use useEffect for data fetching
- ✅ **Follow existing patterns** - Match codebase style and structure
- ✅ **Type safety first** - Use types from ManagingApi.ts
- ✅ **Error handling** - Services throw user-friendly errors
- ✅ **Query invalidation** - Invalidate related queries after mutations
- ✅ **Component structure** - Functional components, static content at end
- ✅ **Styling** - Use DaisyUI/Tailwind, mobile-first approach
- ⚠️ **Don't update ManagingApi.ts** - It's auto-generated
- ⚠️ **Check existing code** - Reuse components/hooks when possible
- ⚠️ **Test integration** - Verify API calls work correctly
- 📦 **Hook location**: `src/Managing.WebApp/src/hooks/`
- 🔧 **Component location**: `src/Managing.WebApp/src/components/`
- 📄 **Page location**: `src/Managing.WebApp/src/pages/`
- 🗄️ **API types**: Import from `src/Managing.WebApp/src/generated/ManagingApi.ts`