pro-clubs-shared-dtos 3.0.0

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,237 @@
+# Integration Guide - Using @pro-clubs-manager/shared-dtos
+
+## Overview
+This guide explains how to integrate the shared-dtos package in both the client and server applications.
+
+## Installation
+
+### Step 1: Publish the Package
+Once the shared-dtos package is ready, publish it to npm:
+
+```bash
+cd shared-dtos
+npm publish
+```
+
+### Step 2: Install in Client (ProClubsStatsClient)
+
+Update `ProClubsStatsClient/package.json`:
+```json
+{
+  "dependencies": {
+    "@pro-clubs-manager/shared-dtos": "^3.0.0"
+  }
+}
+```
+
+Then run:
+```bash
+npm install
+```
+
+### Step 3: Install in Server (ProClubsStatsServer)
+
+Update `ProClubsStatsServer/package.json`:
+```json
+{
+  "dependencies": {
+    "@pro-clubs-manager/shared-dtos": "^3.0.0"
+  }
+}
+```
+
+Then run:
+```bash
+npm install
+```
+
+## Usage Patterns
+
+### Client (Angular)
+
+```typescript
+import {
+  IUser,
+  ITeam,
+  IPlayer,
+  IGame,
+  EXTENDED_GAME_STATUS,
+  EVENT_TYPE
+} from '@pro-clubs-manager/shared-dtos';
+
+// Use in services
+@Injectable()
+export class PlayerService {
+  getPlayer(id: string): Observable<IPlayer> {
+    return this.http.get<IPlayer>(`/api/players/${id}`);
+  }
+
+  getPlayerTeams(playerId: string): Observable<ITeam[]> {
+    return this.http.get<ITeam[]>(`/api/players/${playerId}/teams`);
+  }
+}
+
+// Use in components
+export class TeamComponent {
+  team: ITeam | null = null;
+  players: IPlayer[] = [];
+
+  constructor(private teamService: TeamService) {}
+
+  loadTeam(teamId: string): void {
+    this.teamService.getTeam(teamId).subscribe(team => {
+      this.team = team;
+    });
+  }
+}
+```
+
+### Server (Express/Node)
+
+```typescript
+import {
+  IUser,
+  ITeam,
+  IPlayer,
+  AddGameData,
+  EXTENDED_GAME_STATUS
+} from '@pro-clubs-manager/shared-dtos';
+
+// Use in services
+@injectable()
+export class PlayerService {
+  async getPlayer(id: string): Promise<IPlayer> {
+    return Player.findById(id);
+  }
+
+  async createPlayer(data: any): Promise<IPlayer> {
+    const player = new Player(data);
+    return player.save();
+  }
+}
+
+// Use in controllers
+@Controller('/players')
+export class PlayerController {
+  @Get(':id')
+  async getPlayer(@Param('id') id: string): Promise<IPlayer> {
+    return this.playerService.getPlayer(id);
+  }
+}
+
+// Use in repositories
+export class PlayerRepository {
+  async findByTeam(teamId: string): Promise<IPlayer[]> {
+    return Player.find({ team: teamId });
+  }
+}
+```
+
+## Import Organization
+
+### Group imports by category
+
+```typescript
+// Models
+import {
+  IUser,
+  ITeam,
+  IPlayer,
+  IGame,
+  ILeague
+} from '@pro-clubs-manager/shared-dtos';
+
+// Types
+import {
+  IPlayerStats,
+  ITeamSeason,
+  PlayerGamePerformance,
+  PlayoffDetails,
+  TeamWithPlayers
+} from '@pro-clubs-manager/shared-dtos';
+
+// Enums
+import {
+  EXTENDED_GAME_STATUS,
+  GAME_STATUS,
+  EVENT_TYPE,
+  EVENT_STATUS,
+  PLAYOFF_STAGE
+} from '@pro-clubs-manager/shared-dtos';
+```
+
+## Breaking Changes and Compatibility
+
+### Version 3.0.0
+- Initial release as centralized package
+- Contains all model interfaces
+- Mongoose is now a dependency
+
+### Backward Compatibility
+- All interfaces remain exactly the same as before
+- No property names or types were changed
+- Existing code should work with just import path changes
+
+## Migration Checklist
+
+- [ ] Publish @pro-clubs-manager/shared-dtos to npm
+- [ ] Install package in ProClubsStatsServer
+- [ ] Update server imports:
+  - [ ] Replace `import from '../models/*'` with shared-dtos (for interfaces only)
+  - [ ] Keep Mongoose model imports local
+  - [ ] Update interface imports in interfaces folder
+- [ ] Install package in ProClubsStatsClient
+- [ ] Update client imports:
+  - [ ] Replace all model imports with shared-dtos
+  - [ ] Update service return types
+  - [ ] Update component model properties
+- [ ] Run tests
+- [ ] Update documentation
+
+## Common Issues and Solutions
+
+### Issue: "Cannot find module '@pro-clubs-manager/shared-dtos'"
+**Solution**: 
+1. Ensure npm install was run
+2. Check package.json has the correct version
+3. Verify npm cache: `npm cache clean --force`
+
+### Issue: "Module has no exported member 'TypeName'"
+**Solution**:
+1. Check the type exists in shared-dtos/src/index.ts
+2. Verify the export path in the index file
+3. Run `npm run build` in shared-dtos folder to regenerate
+
+### Issue: Type mismatches in strict mode
+**Solution**:
+1. Update tsconfig.json strictNullChecks setting
+2. Add proper null checks for optional fields
+3. Use type guards for safety
+
+## Version Management
+
+### Future Updates
+- Bug fixes: Patch version (3.0.x)
+- New models/types: Minor version (3.1.0)
+- Breaking changes: Major version (4.0.0)
+
+Use npm version commands:
+```bash
+npm version patch   # 3.0.0 -> 3.0.1
+npm version minor   # 3.0.0 -> 3.1.0
+npm version major   # 3.0.0 -> 4.0.0
+```
+
+## FAQ
+
+**Q: Should I include the shared-dtos source in version control?**
+A: No, it will be installed via npm. Only include it in the monorepo for development purposes.
+
+**Q: Can I use shared-dtos in other projects?**
+A: Yes! Once published to npm, any TypeScript project can use it.
+
+**Q: How do I add new types to shared-dtos?**
+A: Add the type definition to shared-dtos/src, update index.ts exports, rebuild, and publish a new version.
+
+**Q: Is there a changelog?**
+A: Check MIGRATION_SUMMARY.md for the initial release info.

package/MIGRATION_SUMMARY.md

@@ -0,0 +1,163 @@
+# Shared DTOs Package Migration - Summary
+
+## Objective
+Consolidate all type definitions, interfaces, and models from the backend into a centralized npm package (@pro-clubs-manager/shared-dtos) that can be published and used by both client and server applications.
+
+## What Was Accomplished
+
+### 1. Created Shared DTOs Package Structure
+- **Location**: `/shared-dtos`
+- **Package Name**: `@pro-clubs-manager/shared-dtos`
+- **Version**: `3.0.0`
+
+### 2. Migrated Type Definitions
+Successfully copied and compiled the following from ProClubsStatsServer/src to shared-dtos/src:
+
+#### Models (21 files)
+- User model (IUser)
+- Team model (ITeam, ITeamSeason, TeamWithPlayers)
+- Player model (IPlayer, IPlayerSeason, IPlayerStats, PopulatedPlayerWithTeam)
+- Game model (IGame, PlayerGamePerformance, PlayoffDetails)
+- League model (ILeague)
+- Fixture model (IFixture)
+- Event model (IEvent, IEventStats, IAllStarDraftTeam)
+- News model (INews, ITransferData, IFreeAgentData)
+- Notification model (INotification)
+- Chat model (IChatMessage)
+- Ban model (IBan)
+- Prediction model (IPrediction, PREDICTION_OUTCOME enum)
+- Transfer Request model (ITransferRequest)
+- Season Achievement model (ISeasonAchievement)
+- Team of the Season model (ITeamOfTheSeason, ITeamOfTheSeasonPlayer)
+- Player Association Request model (IPlayerAssociationRequest)
+- Comment model (IComment)
+
+#### Enums
+- **EXTENDED_GAME_STATUS** - Game state management (Scheduled, Played, Completed, etc.)
+- **EVENT_TYPE** - Event type enumeration
+- **EVENT_STATUS** - Event status enumeration
+- **PLAYOFF_STAGE** - Playoff round definitions
+- **SERIES_FORMAT** - Match series format options
+
+### 3. Built Comprehensive Exports
+- **index.ts**: Centralized export file that re-exports all models and enums
+- **114 Type Definition Files** (.d.ts): Compiled TypeScript declarations
+- **114 JavaScript Files** (.js): Compiled JavaScript modules
+
+### 4. Package Configuration
+- **Dependencies**: mongoose ^7.0.0 || ^8.0.0
+- **Peer Dependencies**: mongoose (same versions)
+- **Dev Dependencies**: TypeScript ^5.3.2, @types/node ^20.0.0
+- **Entry Points**:
+  - Main: `dist/index.js`
+  - Types: `dist/index.d.ts`
+
+### 5. Build Status
+✅ **Successfully Compiled**
+- Zero TypeScript compilation errors
+- All models properly exported
+- Type definitions generated
+- Ready for npm publication
+
+## Package Contents
+
+### Key Exports
+```typescript
+// Models
+export * from './models/user';
+export * from './models/team';
+export * from './models/player/player';
+export * from './models/game/game';
+export * from './models/league';
+export * from './models/fixture';
+export * from './models/event';
+export * from './models/news';
+// ... and 14 more model files
+
+// Enums
+export * from './enums/extended-game-status';
+```
+
+### Usage Example
+```typescript
+import {
+  IUser,
+  ITeam,
+  IPlayer,
+  EXTENDED_GAME_STATUS,
+  IPrediction
+} from '@pro-clubs-manager/shared-dtos';
+```
+
+## Next Steps
+
+### Before Publishing to npm:
+1. Update server and client to point to published npm package version
+2. Add any missing DTOs that are currently only defined in controllers/services
+3. Create .npmignore file to exclude src and unnecessary files from publication
+4. Add proper repository and homepage URLs to package.json
+
+### Publishing:
+```bash
+cd shared-dtos
+npm publish
+```
+
+### Integration:
+1. Update ProClubsStatsServer/package.json to use published version
+2. Update ProClubsStatsClient/package.json to use published version
+3. Replace local imports with shared package imports
+
+## Files Modified
+
+### Created
+- `/shared-dtos/src/models/*` (21 files)
+- `/shared-dtos/src/enums/extended-game-status.ts`
+- `/shared-dtos/src/dtos/api-error-response.ts`
+- `/shared-dtos/src/index.ts` (comprehensive export file)
+
+### Updated
+- `/shared-dtos/package.json` - Added mongoose dependency, updated version to 3.0.0
+- `/shared-dtos/README.md` - Documentation
+
+## Architecture Decisions
+
+### What was moved to shared-dtos:
+✅ Pure data models (interfaces)
+✅ Model type definitions
+✅ Enums  
+✅ Mongoose schema types
+
+### What remains in server:
+❌ Service implementations
+❌ Repository implementations
+❌ Controller implementations
+❌ Request/Response DTOs (will be addressed in future phase)
+❌ Service-specific interfaces
+
+This separation allows the shared package to be truly shared and lightweight, while service logic remains in the respective applications.
+
+## Build Artifacts
+
+- **Type Definitions**: 114 .d.ts files in dist/
+- **Compiled JavaScript**: 114 .js files in dist/
+- **Size**: Minimal footprint for quick npm installation
+- **Dependencies**: Only mongoose required
+
+## Success Criteria Met
+
+✅ All 21 models successfully copied and compiled
+✅ All enums properly exported
+✅ No TypeScript compilation errors in shared-dtos
+✅ Complete type definitions generated
+✅ Package ready for npm publication
+✅ Comprehensive export file created
+✅ Package.json properly configured
+
+## Notes
+
+- The package is self-contained and includes all necessary type definitions
+- Mongoose is marked as both dependency and peer dependency to ensure compatibility
+- The build process can be run at any time with `npm run build`
+- Watch mode is available for development with `npm run watch`
+- Clean build available with `npm run clean`

package/README.md

@@ -0,0 +1,284 @@
+# @pro-clubs-manager/shared-dtos
+
+Shared Data Transfer Objects (DTOs) package for Pro Clubs Manager Client and Server. This package contains all common interfaces and types used across the entire application.
+
+## Overview
+
+This is a monorepo package that provides type definitions and DTOs for:
+- **Client** (Angular application)
+- **Server** (Express.js API)
+
+By consolidating DTOs in a single shared package, we ensure:
+- ✅ Type safety across client and server
+- ✅ Single source of truth for data structures
+- ✅ Easier maintenance and refactoring
+- ✅ Better IDE auto-completion and intellisense
+- ✅ Reduced duplication
+
+## Structure
+
+```
+shared-dtos/
+├── src/
+│   ├── dtos/
+│   │   ├── enums/
+│   │   │   └── index.ts              # All enums (GAME_STATUS, EVENT_TYPE, etc.)
+│   │   ├── requests/
+│   │   │   ├── index.ts              # Request DTOs barrel export
+│   │   │   ├── create-player-request.ts
+│   │   │   ├── update-player-data-request.ts
+│   │   │   ├── player-requests.ts
+│   │   │   ├── fixture-requests.ts
+│   │   │   └── game-requests.ts
+│   │   └── responses/
+│   │       ├── index.ts              # Response DTOs barrel export
+│   │       ├── game-dtos.ts          # Game and PlayerPerformance DTOs
+│   │       ├── fixture-dtos.ts       # Fixture DTOs
+│   │       ├── player-dtos.ts        # Player DTOs
+│   │       ├── team-dtos.ts          # Team DTOs
+│   │       ├── league-dtos.ts        # League DTOs
+│   │       ├── stats-dtos.ts         # Stats DTOs
+│   │       ├── event-dtos.ts         # Event DTOs (new)
+│   │       ├── transfer-dtos.ts      # Transfer Request DTOs (new)
+│   │       └── notification-dtos.ts  # Notification DTOs (new)
+│   └── index.ts                      # Main entry point
+├── dist/                             # Compiled JavaScript and type definitions
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Included DTOs
+
+### Enums
+- `GAME_STATUS` - Game states (scheduled, inProgress, completed, etc.)
+- `EVENT_TYPE` - Event types (friendly, league, playoff, allStar, cup)
+- `EVENT_STATUS` - Event states (draft, scheduled, inProgress, completed, cancelled)
+- `SERIES_FORMAT` - Series formats (bestOf1, bestOf3, bestOf5, bestOf7)
+- `TRANSFER_REQUEST_STATUS` - Transfer request states
+- `NOTIFICATION_TYPE` - Notification types
+- `PLAYER_POSITION` - Player positions (ST, CAM, CM, CDM, LM, RM, LB, RB, CB, GK)
+- `CHEMISTRY_STYLE` - FIFA Chemistry styles
+
+### Response DTOs
+
+#### Game DTOs
+- `GameDTO` - Complete game information
+- `PlayerPerformanceDTO` - Player performance stats in a game
+
+#### Player DTOs
+- `PlayerDTO` - Player information and stats
+- `PlayerStatsDTO` - Player season statistics
+- `PlayerLastGamesForm` - Player's last games form
+
+#### Team DTOs
+- `TeamDTO` - Team information
+- `LeagueTableRow` - League table entry
+
+#### Fixture DTOs
+- `FixtureDTO` - Fixture information
+- `PaginatedFixtureDTO` - Paginated fixture list
+
+#### League DTOs
+- `LeagueDTO` - League information
+
+#### Stats DTOs
+- `AdvancedPlayersStats` - Advanced player statistics
+- `TopScorer` - Top scorer information
+- `TopAssister` - Top assister information
+- `TopAvgRating` - Top average rating information
+- `AdvancedTeamStats` - Advanced team statistics
+
+#### Event DTOs
+- `EventDTO` - Event information
+- `CreateEventDTO` - Create event request
+- `EventStatsDTO` - Event statistics
+- `AllStarTeamDTO` - All-Star team information
+- `AllStarDraftConfigDTO` - All-Star draft configuration
+- `RegisterForEventDTO` - Event registration
+- `SelectCaptainsDTO` - Captain selection
+- `AddPlayerToDraftTeamDTO` - Add player to draft team
+- `FinishDraftDTO` - Finish draft
+- `UpdateEventStatsDTO` - Update event stats
+
+#### Transfer DTOs
+- `TransferRequestDTO` - Transfer request information
+- `PaginatedTransferRequestsDTO` - Paginated transfer requests
+- `CreateTransferRequestDTO` - Create transfer request
+- `ProcessTransferRequestDTO` - Process transfer request
+
+#### Notification DTOs
+- `NotificationDTO` - Notification information
+- `CreateNotificationDTO` - Create notification
+
+### Request DTOs
+
+#### Player Requests
+- `CreatePlayerRequestDTO` - Create player request
+- `UpdatePlayerDataRequestDTO` - Update player data request
+- `PlayerRequestDTO` - Player request
+
+#### Fixture Requests
+- `CreateFixtureRequestDTO` - Create fixture request
+- `UpdateFixtureRequestDTO` - Update fixture request
+
+#### Game Requests
+- `CreateGameRequestDTO` - Create game request
+- `UpdateGameRequestDTO` - Update game request
+
+## Usage
+
+### Installation
+
+The shared-dtos package is referenced locally in both client and server `package.json` files:
+
+```json
+"@pro-clubs-manager/shared-dtos": "file:../shared-dtos"
+```
+
+### Importing DTOs
+
+**In the Client (Angular):**
+```typescript
+import { PlayerDTO, TeamDTO, GAME_STATUS } from '@pro-clubs-manager/shared-dtos';
+
+// Use in your components
+export class PlayerComponent {
+  player: PlayerDTO;
+  gameStatus = GAME_STATUS;
+}
+```
+
+**In the Server (Express):**
+```typescript
+import { PlayerDTO, GameDTO, CreateGameRequestDTO } from '@pro-clubs-manager/shared-dtos';
+
+// Use in your services and controllers
+app.post('/games', (req: Request<{}, {}, CreateGameRequestDTO>, res: Response) => {
+  // Implementation
+});
+```
+
+### Specific Import Paths
+
+For more specific imports:
+
+```typescript
+// Import enums
+import { GAME_STATUS, EVENT_TYPE } from '@pro-clubs-manager/shared-dtos';
+
+// Import response DTOs
+import { PlayerDTO, GameDTO } from '@pro-clubs-manager/shared-dtos';
+
+// Import request DTOs
+import { CreatePlayerRequestDTO, UpdateFixtureRequestDTO } from '@pro-clubs-manager/shared-dtos';
+```
+
+## Development
+
+### Building the Package
+
+```bash
+cd shared-dtos
+npm run build
+```
+
+This compiles TypeScript to JavaScript and generates type definition files in the `dist/` folder.
+
+### Watching for Changes
+
+```bash
+cd shared-dtos
+npm run watch
+```
+
+This watches for changes and automatically recompiles.
+
+### Adding New DTOs
+
+1. Create a new file in the appropriate folder (`enums/`, `requests/`, or `responses/`)
+2. Export your interfaces/types
+3. Add the export to the folder's `index.ts`
+4. The main entry point (`src/index.ts`) automatically exports everything
+5. Run `npm run build` to compile
+
+Example: Adding a new `User` DTO
+
+```typescript
+// src/dtos/responses/user-dtos.ts
+export interface UserDTO {
+  id: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  role: 'admin' | 'captain' | 'player';
+}
+```
+
+Then it's automatically available throughout the application.
+
+## Updating Projects
+
+When you modify the shared-dtos package:
+
+1. **Build the package**: `npm run build` in the `shared-dtos` folder
+2. **No need to reinstall**: The `file:` protocol means the client and server will automatically use the latest build
+3. **Restart dev servers**: If using `npm start` or `ng serve`, restart to pick up changes
+
+## Best Practices
+
+1. **Keep DTOs focused** - Each DTO should represent a specific data structure
+2. **Use meaningful names** - Follow the `<Name>DTO` or `<Action><Name>DTO` convention
+3. **Document complex types** - Add JSDoc comments for clarity
+4. **Avoid circular dependencies** - Keep DTO dependencies simple
+5. **Version carefully** - When making breaking changes, update the package version
+6. **Test imports** - After adding new DTOs, ensure they import correctly in both client and server
+
+## Migration Guide
+
+### From NPM Package to Local Package
+
+The package was migrated from a published NPM package (`@pro-clubs-manager/shared-dtos@1.x`) to a local monorepo package for easier development and updates.
+
+**What Changed:**
+- All DTOs are now in `shared-dtos/src/`
+- Local package is automatically built and linked
+- Changes are immediately reflected (after rebuild)
+- No need to publish to NPM for local development
+
+**What Stayed the Same:**
+- Import paths remain identical: `@pro-clubs-manager/shared-dtos`
+- All existing DTOs are included
+- New DTOs added (event, transfer, notification)
+
+## Troubleshooting
+
+### DTOs not updating in IDE
+
+- Clear TypeScript cache: Delete `shared-dtos/dist/`
+- Run `npm run build`
+- Restart your IDE
+
+### Import errors in client/server
+
+- Ensure `npm install` was run in both client and server after updating `package.json`
+- Check that the import path is correct
+- Verify the DTO is exported in `src/index.ts`
+
+### Build errors
+
+- Run `npm run clean` then `npm run build` in the shared-dtos folder
+- Check for TypeScript errors in the source files
+- Ensure TypeScript version is compatible (^5.3.2)
+
+## Future Enhancements
+
+- Add more comprehensive JSDoc comments
+- Create example usage files
+- Add validation schemas (using libraries like Zod or Joi)
+- Publish to NPM for external consumption
+- Add comprehensive test coverage
+
+## Support
+
+For issues or questions about the shared-dtos package, refer to the main project documentation or create an issue in the repository.

package/dist/dtos/api-error-response.d.ts

@@ -0,0 +1,33 @@
+export interface ApiErrorResponse {
+    statusCode: number;
+    message: string;
+    errorCode?: string;
+    details?: {
+        [key: string]: any;
+    };
+    timestamp?: string;
+    path?: string;
+}
+export declare enum ErrorCode {
+    BAD_REQUEST = "BAD_REQUEST",
+    INVALID_INPUT = "INVALID_INPUT",
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    FORBIDDEN = "FORBIDDEN",
+    NOT_FOUND = "NOT_FOUND",
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
+    CONFLICT = "CONFLICT",
+    DUPLICATE_ENTRY = "DUPLICATE_ENTRY",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
+    DATABASE_ERROR = "DATABASE_ERROR",
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
+    FILE_UPLOAD_ERROR = "FILE_UPLOAD_ERROR",
+    PLAYER_ASSOCIATION_ERROR = "PLAYER_ASSOCIATION_ERROR",
+    TRANSFER_REQUEST_ERROR = "TRANSFER_REQUEST_ERROR",
+    TEAM_ERROR = "TEAM_ERROR",
+    PLAYER_ERROR = "PLAYER_ERROR",
+    USER_ERROR = "USER_ERROR"
+}
+//# sourceMappingURL=api-error-response.d.ts.map