major-domo-v2/commands/transactions/CLAUDE.md

Transaction Commands

This directory contains Discord slash commands for transaction management and roster legality checking.

Files

management.py

• Commands:
  • /mymoves - View user's pending and scheduled transactions
  • /legal - Check roster legality for current and next week
• Service Dependencies:
  • transaction_service (multiple methods for transaction retrieval)
  • roster_service (roster validation and retrieval)
  • team_service.get_teams_by_owner() and get_team_by_abbrev()

dropadd.py

• Commands:
  • /dropadd - Interactive transaction builder for single-team roster moves (scheduled for next week)
  • /cleartransaction - Clear current transaction builder
• Service Dependencies:
  • transaction_builder (transaction creation and validation)
  • player_service.search_players() (player autocomplete)
  • team_service.get_teams_by_owner()

ilmove.py (NEW - October 2025)

• Commands:
  • /ilmove - Interactive transaction builder for real-time roster moves (executed immediately for THIS week)
  • /clearilmove - Clear current IL move transaction builder
• Service Dependencies:
  • transaction_builder (transaction creation and validation - shared with /dropadd)
  • transaction_service.create_transaction_batch() (POST transactions to database)
  • player_service.search_players() (player autocomplete)
  • player_service.update_player_team() (immediate team assignment updates)
  • team_service.get_teams_by_owner()
• Key Differences from /dropadd:
  • Week: Creates transactions for THIS week (current) instead of next week
  • Execution: Immediately POSTs to database and updates player teams
  • Use Case: Real-time IL moves, activations, emergency roster changes
  • UI: Same interactive transaction builder with "immediate" submission handler

trade.py

• Commands:
  • /trade initiate - Start a new multi-team trade
  • /trade add-team - Add additional teams to trade (3+ team trades)
  • /trade add-player - Add player exchanges between teams
  • /trade supplementary - Add internal organizational moves for roster legality
  • /trade view - View current trade status
  • /trade clear - Clear current trade
• Service Dependencies:
  • trade_builder (multi-team trade management)
  • player_service.search_players() (player autocomplete)
  • team_service.get_teams_by_owner(), get_team_by_abbrev(), and get_team()
• Channel Management:
  • Automatically creates private discussion channels for trades
  • Uses TradeChannelManager and TradeChannelTracker for channel lifecycle
  • Requires bot to have Manage Channels permission at server level

Key Features

Transaction Status Display (/mymoves)

• User Team Detection: Automatically finds user's team by Discord ID
• Transaction Categories:
  • Pending: Transactions awaiting processing
  • Frozen: Scheduled transactions ready for processing
  • Processed: Recently completed transactions
  • Cancelled: Optional display of cancelled transactions
• Status Visualization:
  • Status emojis for each transaction type
  • Week numbering and move descriptions
  • Transaction count summaries
• Smart Limiting: Shows recent transactions (last 5 pending, 3 frozen/processed, 2 cancelled)

Roster Legality Checking (/legal)

• Dual Roster Validation: Checks both current and next week rosters
• Flexible Team Selection:
  • Auto-detects user's team
  • Allows manual team specification via abbreviation
• Comprehensive Validation:
  • Player count verification (active roster + IL)
  • sWAR calculations and limits
  • League rule compliance checking
  • Error and warning categorization
• Parallel Processing: Roster retrieval and validation run concurrently

Real-Time IL Move System (/ilmove) (NEW - October 2025)

• Immediate Execution: Transactions posted to database and players moved in real-time
• Current Week Transactions: All moves effective for THIS week, not next week
• Shared Transaction Builder: Uses same builder as /dropadd for consistency
• Interactive UI: Identical transaction builder interface with validation
• Maximum Code Reuse: 95% code shared with /dropadd, only submission differs

IL Move Command Workflow:

1. /ilmove player:"Mike Trout" destination:"Injured List" - Add first move
   • Shows transaction builder with current move
   • Validates roster legality in real-time
   • Instructions say "Use /ilmove to add more moves"
2. /ilmove player:"Shohei Ohtani" destination:"Major League" - Add second move
   • Adds to same transaction builder (shared with user)
   • Shows updated roster projections with both moves
   • Validates combined impact on roster limits
3. Submit via "Submit Transaction" button - Click to execute
   • Shows CONFIRM modal (type "CONFIRM")
   • Immediately POSTs all transactions to database API
   • Immediately updates each player's team_id in database
   • Success message shows database transaction IDs
4. Players show on new teams instantly - Real-time roster changes

IL Move vs Drop/Add Comparison:

Feature	/dropadd	/ilmove
Effective Week	Next week (current + 1)	THIS week (current)
Execution	Scheduled (background task)	Immediate (real-time)
Database POST	No (builder only)	Yes (POSTs to API)
Player Teams	Unchanged until processing	Updated immediately
Use Case	Future planning	IL moves, activations
Destination Options	ML, MiL, FA	ML, MiL, IL
Builder Shared	Yes (same TransactionBuilder)	Yes (same TransactionBuilder)

Real-Time Execution Flow:

1. User submits transaction → Modal confirmation
2. Create Transaction objects → For current week
3. POST to database API → transaction_service.create_transaction_batch()
4. Update player teams → player_service.update_player_team() for each player
5. Success confirmation → Shows actual database IDs and completed status

Important Notes:

• /ilmove only works for players on your roster (not FA signings)
• Players must exist on ML, MiL, or IL rosters
• Cannot use /ilmove to sign free agents (use /dropadd for that)
• All roster legality rules still apply (limits, sWAR, etc.)

Multi-Team Trade System (/trade)

• Trade Initiation: Start trades between multiple teams using proper Discord command groups
• Team Management: Add/remove teams to create complex multi-team trades (2+ teams supported)
• Player Exchanges: Add cross-team player movements with source and destination validation
• Supplementary Moves: Add internal organizational moves for roster legality compliance
• Interactive UI: Rich Discord embeds with validation feedback and trade status
• Real-time Validation: Live roster checking across all participating teams
• Authority Model: Major League team owners control all players in their organization (ML/MiL/IL)

Trade Command Workflow:

1. /trade initiate other_team:LAA - Start trade between your team and LAA
   • Creates a private discussion channel for the trade
   • Only you see the ephemeral response
2. /trade add-team other_team:BOS - Add BOS for 3-team trade
   • Updates are posted to the trade channel if executed elsewhere
   • Other team members can see the progress
3. /trade add-player player_name:"Mike Trout" destination_team:BOS - Exchange players
   • Trade embed updates posted to dedicated channel automatically
   • Keeps all participants informed of changes
4. /trade supplementary player_name:"Player X" destination:ml - Internal roster moves
   • Channel receives real-time updates
5. /trade view - Review complete trade with validation
   • Posts current state to trade channel if viewed elsewhere
6. Submit via interactive UI - Trade submission through Discord buttons

Channel Behavior:

• Commands executed in the trade channel: Only ephemeral response to user
• Commands executed outside trade channel: Ephemeral response to user + public post to trade channel
• This ensures all participating teams stay informed of trade progress

Autocomplete System:

• Team Initiation: Only Major League teams (ML team owners initiate trades)
• Player Destinations: All roster types (ML/MiL/IL) available for player placement
• Player Search: Prioritizes user's team players, supports fuzzy name matching
• Smart Filtering: Context-aware suggestions based on user permissions

Trade Channel Management (trade_channels.py, trade_channel_tracker.py):

• Automatic Channel Creation: Private discussion channels created when trades are initiated
• Channel Naming: Format trade-{team1}-{team2}-{short_id} (e.g., trade-wv-por-681f)
• Permission Management:
  • Channel hidden from @everyone
  • Only participating team roles can view/message
  • Bot has view and send message permissions
  • Created in "Transactions" category (if it exists)
• Channel Tracking: JSON-based persistence for cleanup and management
• Multi-Team Support: Channels automatically update when teams are added to trades
• Automatic Cleanup: Channels deleted when trades are cleared
• Smart Updates: When trade commands are executed outside the dedicated trade channel, the trade embed is automatically posted to the trade channel (non-ephemeral) for visibility

Bot Permission Requirements:

• Server-level Manage Channels - Required to create/delete trade channels
• Server-level Manage Permissions - Optional, for enhanced permission management
• Note: Bot should NOT have these permissions in channel-specific overwrites (causes Discord API error 50013)

Recent Fix (January 2025):

• Removed manage_channels and manage_permissions from bot's channel-specific overwrites
• Discord prohibits bots from granting themselves elevated permissions in channel overwrites
• Server-level permissions are sufficient for all channel management operations

Advanced Transaction Features

• Concurrent Data Fetching: Multiple transaction types retrieved in parallel
• Owner-Based Filtering: Transactions filtered by team ownership
• Status Tracking: Real-time transaction status with emoji indicators
• Team Integration: Team logos and colors in transaction displays

Architecture Notes

Permission Model

• Team Ownership: Commands use Discord user ID to determine team ownership
• Cross-Team Viewing: /legal allows checking other teams' roster status
• Access Control: Users can only view their own transactions via /mymoves

Data Processing

• Async Operations: Heavy use of asyncio.gather() for performance
• Error Resilience: Graceful handling of missing roster data
• Validation Pipeline: Multi-step roster validation with detailed feedback

Embed Structure

• Status-Based Coloring: Success (green) vs Error (red) color coding
• Information Hierarchy: Important information prioritized in embed layout
• Team Branding: Consistent use of team thumbnails and colors

Troubleshooting

Common Issues

1. User team not found:

   • Verify user has team ownership record in database
   • Check Discord user ID mapping to team ownership
   • Ensure current season team assignments are correct

2. Transaction data missing:

   • Verify transaction_service API endpoints are functional
   • Check transaction status filtering logic
   • Ensure transaction records exist for the team/season

3. Roster validation failing:

   • Check roster_service.get_current_roster() and get_next_roster() responses
   • Verify roster validation rules and logic
   • Ensure player data integrity in roster records

4. Legal command errors:

   • Verify team abbreviation exists in database
   • Check roster data availability for both current and next weeks
   • Ensure validation service handles edge cases properly

5. Trade channel creation fails (Fixed January 2025):

   • Error: Discord error: Missing Permissions. Code: 50013
   • Root Cause: Bot was trying to grant itself manage_channels and manage_permissions in channel-specific permission overwrites
   • Fix: Removed elevated permissions from channel overwrites (line 74-77 in trade_channels.py)
   • Verification: Bot only needs server-level Manage Channels permission
   • Channels now create successfully with basic bot permissions (view, send messages, read history)

6. AttributeError when adding players to trades (Fixed January 2025):

   • Error: 'TeamService' object has no attribute 'get_team_by_id'
   • Root Cause: Code was calling non-existent method team_service.get_team_by_id()
   • Fix: Changed to correct method name team_service.get_team() (line 201 in trade_builder.py)
   • Location: services/trade_builder.py and test mocks in tests/test_services_trade_builder.py
   • All 18 trade builder tests pass after fix

Service Dependencies

• services.transaction_service:
  • get_pending_transactions()
  • get_frozen_transactions()
  • get_processed_transactions()
  • get_team_transactions()
  • create_transaction_batch() (NEW - for /ilmove) - POST transactions to database
• services.roster_service:
  • get_current_roster()
  • get_next_roster()
  • validate_roster()
• services.team_service:
  • get_teams_by_owner()
  • get_team_by_abbrev()
  • get_teams_by_season() (trade autocomplete)
• services.trade_builder:
  • TradeBuilder class for multi-team transaction management
  • get_trade_builder() and clear_trade_builder() cache functions
  • TradeValidationResult for comprehensive trade validation
• services.transaction_builder:
  • TransactionBuilder class for single-team roster moves (shared by /dropadd and /ilmove)
  • get_transaction_builder() and clear_transaction_builder() cache functions
  • RosterValidationResult for roster legality validation
• services.player_service:
  • search_players() for autocomplete functionality
  • update_player_team() (NEW - for /ilmove) - Update player team assignments

Core Dependencies

• utils.decorators.logged_command
• views.embeds.EmbedTemplate
• views.trade_embed (NEW): Trade-specific UI components
• utils.autocomplete (ENHANCED): Player and team autocomplete functions
• utils.team_utils (NEW): Shared team validation utilities
• constants.SBA_CURRENT_SEASON

Testing

Run tests with:

• python -m pytest tests/test_commands_transactions.py -v (management commands)
• python -m pytest tests/test_models_trade.py -v (NEW) (trade models)
• python -m pytest tests/test_services_trade_builder.py -v (NEW) (trade builder service)

Database Requirements

• Team ownership mapping (Discord user ID to team)
• Transaction records with status tracking
• Roster data for current and next weeks
• Player assignments and position information
• League rules and validation criteria

Recent Enhancements

October 2025

• ✅ Real-Time IL Move System (/ilmove): Immediate transaction execution for current week roster changes
  • 95% code reuse with /dropadd via shared TransactionBuilder
  • Immediate database POST and player team updates
  • Same interactive UI with "immediate" submission handler
  • Supports multiple moves in single transaction

Previous Enhancements

• ✅ Multi-Team Trade System: Complete /trade command group for 2+ team trades
• ✅ Enhanced Autocomplete: Major League team filtering and smart player suggestions
• ✅ Shared Utilities: Reusable team validation and autocomplete functions
• ✅ Comprehensive Testing: Factory-based tests for trade models and services
• ✅ Interactive Trade UI: Rich Discord embeds with real-time validation

Future Enhancements

• Trade Submission Integration: Connect trade system to transaction processing pipeline
• **Advanced transaction analytics and history
• Trade Approval Workflow: Multi-party trade approval system
• **Roster optimization suggestions
• **Automated roster validation alerts
• Trade History Tracking: Complete audit trail for multi-team trades

Security Considerations

• User authentication via Discord IDs
• Team ownership verification for sensitive operations
• Transaction privacy (users can only see their own transactions)
• Input validation for team abbreviations and parameters