playchoo-manager-nextjs/API.md

# API Endpoints Documentation

## Complete API Endpoints Usage Map

### 🔐 Authentication & Session

#### `/login` (POST)
```
└── token-login/[token]/page.tsx:57
```

#### `/logout` (POST)
```
├── logout/page.tsx:45
└── components/SessionTimeoutModal.tsx:31
```

#### `/user/context` (GET)
```
├── claim-credentials/page.tsx:67
├── components/ClaimCredentialsModal.tsx:70
└── contexts/UserSettingsContext.tsx:64
```

---

### 👤 User Management

#### `/user/bookings` (GET)
```
├── hooks/usePastBookings.ts:14
├── hooks/useUserBookings.ts:35
└── components/UserBookingsTimeline.tsx:44
```

#### `/user/default_remote_sport` (POST)
```
└── select-remote/page.tsx:61
```

#### `/credentials/claim` (POST/PATCH)
```
├── claim-credentials/page.tsx:47
└── components/ClaimCredentialsModal.tsx:50
```

---

### 🏢 Remotes/Clubs

#### `/remotes` (GET)
```
├── select-remote/page.tsx:33
├── settings/page.tsx:50
└── components/RemoteSportInfo.tsx:49
```

---

### 📅 Court Slots & Availability

#### `/day/[date]/slots/[remote_slug]/[sport_slug]` (GET)
```
└── hooks/useCourtSlots.ts:62
    └── booking/[remote_slug]/[sport_slug]/[date]/page.tsx
```

---

### 🎾 Bookings

#### `/booking/[slot_id]` (GET/DELETE)
```
├── booking/slot/[slot_id]/page.tsx:66
└── booking/new/[slot_id]/page.tsx:201
```

#### `/booking/[remote_slug]/[sport_slug]` (POST)
```
└── booking/new/[slot_id]/page.tsx:263
```

#### `/booking/[slot_id]/change-positions` (POST)
```
└── utils/bookingDetailUtils.ts:58
    └── booking/slot/[slot_id]/page.tsx
        └── confirmOrderChange()
```

#### `/booking/[slot_id]/players/[index]` (PATCH)
```
└── utils/bookingDetailUtils.ts
    ├── :105 → cancelRequestGen()
    ├── :146 → rejectRequestGen()
    └── :187 → approveRequestGen()
        └── booking/slot/[slot_id]/page.tsx
```

---

### 🤝 Join Requests

#### `/booking/join-request/[slot_id]` (POST)
```
├── utils/joinRequests.ts:5
└── components/CourtSlotCard.tsx:84
    └── booking/[remote_slug]/[sport_slug]/[date]/page.tsx:97
```

#### `/booking/join-request/pending/[remote_slug]/[sport_slug]` (GET)
```
└── utils/joinRequests.ts:11
```

#### `/booking/join-request/[request_id]/accept` (POST)
```
└── utils/joinRequests.ts:14
    └── booking/slot/[slot_id]/page.tsx
```

#### `/booking/join-request/[request_id]/reject` (POST)
```
└── utils/joinRequests.ts:20
    └── booking/slot/[slot_id]/page.tsx
```

---

### 🏆 Match Results

#### `/booking/[slot_id]/match/result` (POST/PATCH)
```
├── components/ScoreSubmissionModal.tsx:201
├── components/MatchResultDisplay.tsx:65,81
└── booking/slot/[slot_id]/page.tsx:427
```

#### `/booking/[slot_id]/match/result/[won]` (POST)
```
└── components/ScoreSubmissionModal.tsx:234
```

---

### 🔍 Search & Profiles

#### `/players/search/[remote_slug]/[sport_slug]/[search_text]` (GET)
```
└── components/PartnerSearchModal.tsx:231
    ├── booking/new/[slot_id]/page.tsx
    └── booking/slot/[slot_id]/page.tsx
```

#### `/[type]/[id]/public/[sportSlug]` (GET)
```
├── components/profile/ProfileView.tsx:144
└── components/PartnerSearchModal.tsx:279,289
```

---

### 🆕 Match Type Management

#### `/booking/[slot_id]/match-type` (PATCH)
```
└── booking/slot/[slot_id]/page.tsx:629
```

#### `/booking/match-type-request/[request_id]/approve` (POST)
```
└── booking/slot/[slot_id]/page.tsx:653
```

#### `/booking/match-type-request/[request_id]/reject` (POST)
```
└── booking/slot/[slot_id]/page.tsx:675
```

---

## API Architecture Patterns

### Component Hierarchy for Booking Management
```
BookingDetailPage → bookingDetailUtils.ts → API calls
├── confirmOrderChange → /booking/[slot_id]/change-positions
├── Position requests → /booking/[slot_id]/players/[index]
├── Join requests → /booking/join-request/[request_id]/{accept,reject}
├── Score submission → /booking/[slot_id]/match/result
└── Match type changes → /booking/[slot_id]/match-type
```

### Search & Profile Flow
```
PartnerSearchModal
├── Search: /players/search/[remote_slug]/[sport_slug]/[search_text]
├── Profile fetch: /[type]/[id]/public/[sportSlug]
└── Used by: NewBookingPage, BookingDetailPage
```

### Court Slots & Booking Flow
```
BookingPage → useCourtSlots → /day/[date]/slots/[remote_slug]/[sport_slug]
NewBookingPage → /booking/[remote_slug]/[sport_slug]
BookingDetailPage → /booking/[slot_id]
```

### User Management Flow
```
SelectRemotePage → /remotes → /user/default_remote_sport
ClaimCredentialsPage → /credentials/claim → /user/context
LogoutPage → /logout
```

## Notes

- All API calls use the `apiFetch` utility function which:
  - Extracts locale from `window.location.pathname` and sends via `X-Locale` header
  - Automatically adds `X-Timezone` header with user's timezone
  - Includes session cookies for authentication (`credentials: 'include'`)
  - Handles 401 responses by redirecting to login

- **API Path Format**: All endpoints are called directly (e.g., `/user/bookings`, `/day/2025-10-22/slots/...`)
  - No `/api/` prefix needed (removed in Oct 2025 refactor)
  - No `/${locale}/` prefix needed (locale sent via header)

- **Response Types**: Type definitions are in `/src/lib/types.ts`, but many API responses lack comprehensive TypeScript types. Component-level interfaces may exist (e.g., `PlayerProfile` in PartnerSearchModal.tsx).

- Recently migrated from Next.js API proxy to direct Python backend (Oct 2025):
  - Removed `/api/` prefix from all endpoints
  - Changed `/booking/new/[remote_slug]/[sport_slug]` → `/booking/[remote_slug]/[sport_slug]`
  - Changed `/booking/[slot_id]/player-position/[position]` → `/booking/[slot_id]/players/[index]`
  - All endpoints now call Python backend directly via `apiFetch()` utility

## Known Issues

### Assessment API Mismatch
The frontend calls `/assessment/next` (POST) in `assessmentApi.ts:143`, but this endpoint doesn't exist in the Python backend. The backend has:
- `/assessment/answer` (POST) - Save a single answer
- `/assessment/session/<session_id>/continue` (GET) - Continue existing session

This may need to be refactored to use the correct backend endpoints or the backend needs to implement `/assessment/next`.