strat-gameplay-webapp/frontend-sba/types/player.ts

/**
 * Player and Lineup Types
 *
 * TypeScript definitions for SBA player models.
 * Matches backend SbaPlayer and Lineup structures.
 *
 * Backend Reference: app/models/player_models.py
 */

/**
 * SBA Player - Simple player model
 * Backend: SbaPlayer
 */
export interface SbaPlayer {
  // Identity
  id: number
  name: string

  // Images
  image: string
  image2?: string | null
  headshot?: string | null
  vanity_card?: string | null

  // Positions (up to 8)
  pos_1?: string | null
  pos_2?: string | null
  pos_3?: string | null
  pos_4?: string | null
  pos_5?: string | null
  pos_6?: string | null
  pos_7?: string | null
  pos_8?: string | null

  // Stats
  wara?: number | null

  // Team info
  team_id?: number | null
  team_name?: string | null
  season?: string | null

  // References
  strat_code?: string | null
  bbref_id?: string | null
  injury_rating?: string | null
}

/**
 * Lineup entry - player assignment in a game
 * Backend: Lineup (db model) via WebSocket lineup_data event
 */
export interface Lineup {
  lineup_id: number           // Unique lineup entry ID (was 'id')
  card_id: number             // Player/card ID
  game_id?: string            // Optional - not always sent in events
  team_id?: number            // Optional - not always sent in events
  position: string
  batting_order: number | null
  is_starter: boolean
  is_active: boolean
  entered_inning?: number     // Optional - not always sent in events

  // Substitution tracking (optional - not always sent in events)
  replacing_id?: number | null
  after_play?: number | null
  is_fatigued?: boolean

  // Player data (embedded from SBA API)
  player: {
    id: number
    name: string
    image: string     // Card image
    headshot: string  // Headshot for UI circles
  }
}

/**
 * Team lineup - collection of players for a team
 */
export interface TeamLineup {
  team_id: number
  players: Lineup[]
}

/**
 * Bench player from RosterLink (for substitutions)
 * Backend: SbaRosterLinkData with computed is_pitcher/is_batter
 *
 * This is distinct from Lineup - it represents roster players
 * not currently in the active lineup.
 */
export interface BenchPlayer {
  roster_id: number
  player_id: number
  player_positions: string[]  // Natural positions (e.g., ["SS", "2B"])
  is_pitcher: boolean         // True if player has pitching positions
  is_batter: boolean          // True if player has batting positions

  // Player data (from SBA API)
  player: {
    id: number
    name: string
    image: string
    headshot: string
    // Legacy position fields for backwards compatibility
    pos_1: string | null
    pos_2: string | null
    pos_3: string | null
  }
}

/**
 * Lineup data response from server
 */
export interface LineupDataResponse {
  game_id: string
  team_id: number
  players: Lineup[]
}

/**
 * Substitution types
 */
export type SubstitutionType = 'pinch_hitter' | 'defensive_replacement' | 'pitching_change'

/**
 * Substitution request
 */
export interface SubstitutionRequest {
  game_id: string
  type: SubstitutionType
  player_out_lineup_id: number
  player_in_card_id: number
  team_id: number
  new_position?: string  // Required for defensive replacement
}

/**
 * Substitution result from server
 */
export interface SubstitutionResult {
  type: SubstitutionType
  player_out_lineup_id: number
  player_in_card_id: number
  new_lineup_id: number
  position: string
  batting_order: number | null
  team_id: number
  message: string
}

/**
 * Substitution error codes
 */
export type SubstitutionErrorCode =
  | 'MISSING_FIELD'
  | 'INVALID_FORMAT'
  | 'NOT_CURRENT_BATTER'
  | 'PLAYER_ALREADY_OUT'
  | 'NOT_IN_ROSTER'
  | 'ALREADY_ACTIVE'
  | 'INVALID_POSITION'

/**
 * Substitution error response
 */
export interface SubstitutionError {
  code: SubstitutionErrorCode
  message: string
  field?: string
}