# API v2 Migration Guide

## Status: In Progress

The web app is being migrated to use API v2 exclusively. API v2 provides:
- Standard OAuth2/JWT Bearer token authentication
- RESTful endpoint patterns
- Better error handling with standard HTTP status codes
- Token refresh mechanism

## Backend Implementation Status

### ✅ Completed
- [x] Created `AuthApiV2` with OAuth2 endpoints
- [x] Created `JwtService` for token generation/verification
- [x] Created `authorizeV2` middleware for Bearer token auth
- [x] Created `PacksApiV2` basic structure
- [x] Mounted v2 APIs at `/api/v2` path
- [x] Separated v1 and v2 authorization middleware

### ⚠️ Needs Completion
- [ ] Fix JwtService HMAC-SHA256 implementation (use proper crypto library)
- [ ] Complete PacksApiV2 endpoints implementation
- [ ] Implement TestsApiV2
- [ ] Implement GamesApiV2
- [ ] Implement PurchasesApiV2
- [ ] Implement SubscriptionsApiV2
- [ ] Implement PromocodesApiV2
- [ ] Add comprehensive error responses
- [ ] Add API documentation (OpenAPI/Swagger)

## Web App Implementation Status

### ✅ Completed
- [x] Created `ApiConfigV2` with all v2 endpoints
- [x] Created `HttpRepositoryV2` with Bearer token auth
- [x] Updated `StorageModule` to use HttpRepositoryV2
- [x] Updated `AuthService` to use HttpRepositoryV2
- [x] Updated dependency injection to use v2

### ⚠️ Needs Completion
- [x] Update `GamesManager` to use HttpRepositoryV2
- [x] Update `TestManager` to use HttpRepositoryV2
- [ ] Update `StatisticsService` to use HttpRepositoryV2
- [x] Update `SubscriptionService` to use HttpRepositoryV2
- [x] Update `PromocodeService` to use HttpRepositoryV2
- [ ] Update `PackProgressService` to use HttpRepositoryV2
- [ ] Write unit tests for HttpRepositoryV2
- [ ] Update integration tests

## Backend Endpoints

### Authentication (`/api/v2/auth`)
- `POST /api/v2/auth/oauth/google` - Google OAuth
- `POST /api/v2/auth/refresh` - Refresh access token
- `GET /api/v2/auth/me` - Get current user
- `POST /api/v2/auth/logout` - Logout

### Packs (`/api/v2/packs`)
- `GET /api/v2/packs` - List packs (with pagination)
- `GET /api/v2/packs/{packId}` - Get pack details
- `GET /api/v2/packs/{packId}/cards` - Get pack cards
- `GET /api/v2/packs/{packId}/cards/{cardId}/image` - Get card image
- `GET /api/v2/packs/{packId}/tests` - Get pack tests

### Tests (`/api/v2/tests`)
- `GET /api/v2/tests/{testId}` - Get test
- `POST /api/v2/tests/{testId}/results` - Submit results
- `GET /api/v2/tests/{testId}/history` - Get attempt history

## Migration Steps

1. **Backend**: Complete JWT implementation and all v2 endpoints
2. **Web App**: Update all services to use HttpRepositoryV2
3. **Testing**: Write comprehensive tests for v2 endpoints
4. **Deployment**: Deploy backend v2 endpoints
5. **Verification**: Test end-to-end with web app
6. **Deprecation**: Mark v1 APIs as deprecated (keep for mobile app)

## Next Steps

1. Fix JWT service to use proper crypto library
2. Complete backend v2 endpoint implementations
3. Update web app services to use HttpRepositoryV2 methods
4. Write tests
5. Deploy and verify