tastytrade 0.2.0 → 0.3.1

data/README.md

@@ -20,9 +20,11 @@ This Ruby gem provides a simple interface to interact with the Tastytrade API, a
 - Secure authentication with Tastytrade API
 - Real-time market data access
 - Account management and portfolio tracking
-- Order placement and management
+- Order placement and management with dry-run support
 - Position monitoring
-- Transaction history
+- Transaction history with filtering and grouping
+- Buying power calculations and monitoring
+- CLI with interactive mode and rich formatting
 
 ## Roadmap
 
@@ -48,6 +50,30 @@ Or install it yourself as:
 gem install tastytrade
 ```
 
+## Configuration
+
+### Environment Variables
+
+The tastytrade gem supports authentication via environment variables, which is recommended for automation and CI/CD environments:
+
+```bash
+# Required for environment variable authentication
+export TASTYTRADE_USERNAME="your_email@example.com"
+export TASTYTRADE_PASSWORD="your_password"
+
+# Optional environment variables
+export TASTYTRADE_ENVIRONMENT="sandbox"  # Use "sandbox" for test environment
+export TASTYTRADE_REMEMBER="true"        # Enable remember token
+
+# Alternative shorter variable names
+export TT_USERNAME="your_email@example.com"
+export TT_PASSWORD="your_password"
+export TT_ENVIRONMENT="sandbox"
+export TT_REMEMBER="true"
+```
+
+When environment variables are set, the CLI will automatically use them for authentication without prompting for credentials.
+
 ## Usage
 
 ### Authentication
@@ -75,19 +101,165 @@ session.authenticated? # => true
 
 The gem includes a command-line interface for common operations:
 
+#### Authentication
+
 ```bash
-# Login to your account
+# Login to your account interactively
 tastytrade login
 
 # Login with remember option for automatic session refresh
 tastytrade login --remember
 
+# Login using environment variables (recommended for automation)
+export TASTYTRADE_USERNAME="your_email@example.com"
+export TASTYTRADE_PASSWORD="your_password"
+tastytrade login
+
+# Or use shorter variable names
+export TT_USERNAME="your_email@example.com"
+export TT_PASSWORD="your_password"
+tastytrade login
+
+# Use sandbox environment for testing
+export TASTYTRADE_ENVIRONMENT="sandbox"
+tastytrade login
+
+# Enable remember token via environment
+export TASTYTRADE_REMEMBER="true"
+tastytrade login
+
+```
+
+#### Account Operations
+
+```bash
 # View account balances
 tastytrade balance
 
 # View balances for all accounts
 tastytrade balance --all
 
+# View account positions
+tastytrade positions
+
+# Filter positions by symbol
+tastytrade positions --symbol AAPL
+
+# Filter positions by underlying symbol (for options)
+tastytrade positions --underlying-symbol SPY
+
+# View trading status and permissions
+tastytrade trading_status
+
+# View status for specific account
+tastytrade trading_status --account 5WT0001
+
+# Include closed positions
+tastytrade positions --include-closed
+```
+
+#### Transaction History
+
+```bash
+# View all transactions
+tastytrade history
+
+# Filter by date range
+tastytrade history --start-date 2024-01-01 --end-date 2024-12-31
+
+# Filter by symbol
+tastytrade history --symbol AAPL
+
+# Group transactions by symbol, type, or date
+tastytrade history --group-by symbol
+tastytrade history --group-by type
+tastytrade history --group-by date
+
+# Limit number of transactions
+tastytrade history --limit 50
+
+# Combine filters
+tastytrade history --symbol AAPL --start-date 2024-01-01 --group-by date
+```
+
+#### Buying Power Status
+
+```bash
+# View buying power status
+tastytrade buying_power
+
+# View buying power for specific account
+tastytrade buying_power --account 5WX12345
+```
+
+#### Order Management
+
+##### Order Placement
+
+```bash
+# Place a limit buy order
+tastytrade order place --symbol AAPL --action buy_to_open --quantity 100 --price 150.50
+
+# Place a market order
+tastytrade order place --symbol SPY --action buy_to_open --quantity 10 --type market
+
+# Sell to close a position
+tastytrade order place --symbol AAPL --action sell_to_close --quantity 100 --price 155.00
+
+# Dry-run validation (validate without placing)
+tastytrade order place --symbol MSFT --action buy_to_open --quantity 50 --price 300 --dry-run
+
+# Skip confirmation prompt
+tastytrade order place --symbol TSLA --action buy_to_open --quantity 10 --price 200 --skip-confirmation
+
+# Supported actions:
+# - buy_to_open (bto)
+# - sell_to_close (stc) 
+# - sell_to_open (sto)
+# - buy_to_close (btc)
+
+# Note: Orders that would use >80% of buying power will prompt for confirmation
+```
+
+##### Order Status and History
+
+```bash
+# List all live orders (open + last 24 hours)
+tastytrade order list
+
+# List orders with filters
+tastytrade order list --status Live
+tastytrade order list --symbol AAPL
+tastytrade order list --all  # Show for all accounts
+
+# Output orders in JSON format
+tastytrade order list --format json
+
+# Get historical orders (beyond 24 hours)
+tastytrade order history
+tastytrade order history --status Filled
+tastytrade order history --symbol AAPL
+tastytrade order history --from 2024-01-01 --to 2024-12-31
+tastytrade order history --limit 100
+tastytrade order history --format json
+
+# Get details for a specific order
+tastytrade order get ORDER_ID
+tastytrade order get ORDER_ID --format json
+
+# Cancel an order
+tastytrade order cancel ORDER_ID
+tastytrade order cancel ORDER_ID --account 5WX12345
+
+# Replace/modify an order
+tastytrade order replace ORDER_ID  # Interactive prompts for new price/quantity
+tastytrade order replace ORDER_ID --price 155.00
+tastytrade order replace ORDER_ID --quantity 50
+```
+
+#### Account Management
+
+```bash
 # List all accounts
 tastytrade accounts
 
@@ -129,11 +301,21 @@ balance.cash_balance # => BigDecimal("10000.50")
 balance.net_liquidating_value # => BigDecimal("42001.00")
 balance.equity_buying_power # => BigDecimal("20000.00")
 balance.available_trading_funds # => BigDecimal("12000.00")
+balance.day_trading_buying_power # => BigDecimal("40000.00")
+balance.derivative_buying_power # => BigDecimal("20000.00")
 
 # Check buying power usage
 balance.buying_power_usage_percentage # => BigDecimal("40.00")
+balance.derivative_buying_power_usage_percentage # => BigDecimal("25.00")
 balance.high_buying_power_usage? # => false (checks if > 80%)
 
+# Check if sufficient buying power for order
+balance.sufficient_buying_power?(15000) # => true
+balance.sufficient_buying_power?(15000, buying_power_type: :derivative) # => true
+
+# Calculate buying power impact
+balance.buying_power_impact_percentage(15000) # => BigDecimal("75.00")
+
 # Calculate totals
 balance.total_equity_value # => BigDecimal("30001.00")
 balance.total_derivative_value # => BigDecimal("4500.00")
@@ -168,6 +350,245 @@ positions.each do |position|
 end
 ```
 
+### Order Placement
+
+```ruby
+# Create an order leg for buying stock
+leg = Tastytrade::OrderLeg.new(
+  action: Tastytrade::OrderAction::BUY_TO_OPEN,
+  symbol: 'AAPL',
+  quantity: 100
+)
+
+# Create a market order
+market_order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::MARKET,
+  legs: leg
+)
+
+# Create a limit order
+limit_order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::LIMIT,
+  legs: leg,
+  price: 150.50  # Will be converted to BigDecimal
+)
+
+# Place the order
+response = account.place_order(session, market_order)
+
+# Dry run (simulate order without placing)
+response = account.place_order(session, limit_order, dry_run: true)
+
+# Check order response
+puts response.order_id           # => "123456"
+puts response.status             # => "Filled"
+
+# Dry run orders return a BuyingPowerEffect object
+if response.buying_power_effect.is_a?(Tastytrade::Models::BuyingPowerEffect)
+  bp_effect = response.buying_power_effect
+  puts bp_effect.buying_power_change_amount # => BigDecimal("15050.00")
+  puts bp_effect.buying_power_usage_percentage # => BigDecimal("75.25")
+  puts bp_effect.exceeds_threshold?(80) # => false
+  puts bp_effect.debit? # => true
+else
+  puts response.buying_power_effect # => BigDecimal("-15050.00")
+end
+
+puts response.warnings           # => [] or warning messages
+```
+
+### Order Management
+
+```ruby
+# Get live orders (open orders + orders from last 24 hours)
+orders = account.get_live_orders(session)
+
+# Filter orders by status
+live_orders = account.get_live_orders(session, status: "Live")
+filled_orders = account.get_live_orders(session, status: "Filled")
+
+# Filter orders by symbol
+aapl_orders = account.get_live_orders(session, underlying_symbol: "AAPL")
+
+# Filter by time range
+recent_orders = account.get_live_orders(session,
+  from_time: Time.now - 86400,  # Last 24 hours
+  to_time: Time.now
+)
+
+# Work with order details
+orders.each do |order|
+  puts order.id                  # => "12345"
+  puts order.status              # => "Live"
+  puts order.underlying_symbol   # => "AAPL"
+  puts order.order_type          # => "Limit"
+  puts order.price               # => BigDecimal("150.50")
+  
+  # Check order capabilities
+  puts order.cancellable?        # => true
+  puts order.editable?           # => true
+  puts order.terminal?           # => false
+  puts order.working?            # => true
+  
+  # Check fill status
+  puts order.remaining_quantity  # => 100
+  puts order.filled_quantity     # => 0
+  
+  # Work with order legs
+  order.legs.each do |leg|
+    puts leg.symbol              # => "AAPL"
+    puts leg.action              # => "Buy"
+    puts leg.quantity            # => 100
+    puts leg.remaining_quantity  # => 100
+    puts leg.partially_filled?   # => false
+  end
+end
+
+# Cancel an order
+account.cancel_order(session, "12345")
+
+# Replace an order with new parameters
+new_order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::LIMIT,
+  legs: leg,
+  price: 155.00  # New price
+)
+response = account.replace_order(session, "12345", new_order)
+```
+
+### Order Validation
+
+The SDK includes comprehensive order validation to prevent submission errors and ensure orders meet all requirements before reaching the API.
+
+#### Validation Features
+
+```ruby
+# Orders are automatically validated before submission
+order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::LIMIT,
+  legs: leg,
+  price: 150.00
+)
+
+# Validation happens automatically when placing orders
+begin
+  response = account.place_order(session, order)
+rescue Tastytrade::OrderValidationError => e
+  puts "Validation failed:"
+  e.errors.each { |error| puts "  - #{error}" }
+end
+
+# You can also validate manually
+order.validate!(session, account)  # Raises if invalid
+
+# Or perform a dry-run validation
+dry_run_response = order.dry_run(session, account)
+puts dry_run_response.buying_power_effect
+puts dry_run_response.warnings
+```
+
+#### Validation Rules
+
+The following validations are performed:
+
+1. **Symbol Validation**
+   - Verifies symbol exists and is tradeable
+   - Checks instrument type compatibility
+
+2. **Quantity Validation**
+   - Minimum quantity: 1
+   - Maximum quantity: 999,999
+   - No fractional shares (whole numbers only)
+
+3. **Price Validation**
+   - Price must be positive for limit orders
+   - Price is rounded to appropriate tick size
+   - Price reasonableness checks
+
+4. **Account Permissions**
+   - Validates trading permissions for instrument type
+   - Checks for account restrictions (frozen, closing-only, etc.)
+   - Verifies options/futures permissions if applicable
+
+5. **Buying Power Validation**
+   - Ensures sufficient buying power via dry-run
+   - Warns if order uses >50% of available buying power
+   - Checks margin requirements
+
+6. **Market Hours Validation**
+   - Warns about market orders outside regular hours
+   - Alerts for weekend submissions
+
+#### Validation Errors
+
+```ruby
+# Specific validation error types
+Tastytrade::OrderValidationError     # General validation failure
+Tastytrade::InvalidSymbolError       # Symbol doesn't exist
+Tastytrade::InsufficientBuyingPowerError  # Not enough buying power
+Tastytrade::AccountRestrictedError   # Account has restrictions
+Tastytrade::InvalidQuantityError     # Quantity out of range
+Tastytrade::InvalidPriceError        # Price validation failure
+Tastytrade::MarketClosedError        # Market is closed
+```
+
+#### Using the OrderValidator
+
+```ruby
+# Direct use of OrderValidator for custom validation
+validator = Tastytrade::OrderValidator.new(session, account, order)
+
+# Perform full validation
+validator.validate!  # Raises if invalid
+
+# Or just dry-run validation
+dry_run_response = validator.dry_run_validate!
+
+# Check warnings and errors
+puts validator.warnings  # Array of warning messages
+puts validator.errors    # Array of error messages
+```
+
+#### Skip Validation (Use with Caution)
+
+```ruby
+# Skip validation when you're certain the order is valid
+response = account.place_order(session, order, skip_validation: true)
+```
+
+### Transaction History
+
+```ruby
+# Get all transactions
+transactions = account.get_transactions(session)
+
+# Filter transactions
+transactions = account.get_transactions(session,
+  start_date: Date.new(2024, 1, 1),
+  end_date: Date.new(2024, 12, 31),
+  symbol: 'AAPL',
+  transaction_types: ['Trade'],
+  per_page: 100
+)
+
+# Work with transactions
+transactions.each do |transaction|
+  puts transaction.symbol               # => "AAPL"
+  puts transaction.transaction_type     # => "Trade"
+  puts transaction.transaction_sub_type # => "Buy"
+  puts transaction.quantity             # => BigDecimal("100")
+  puts transaction.price                # => BigDecimal("150.00")
+  puts transaction.value                # => BigDecimal("-15000.00")
+  puts transaction.net_value            # => BigDecimal("-15007.00")
+  puts transaction.executed_at          # => Time object
+  
+  # Fee breakdown
+  puts transaction.commission           # => BigDecimal("5.00")
+  puts transaction.clearing_fees        # => BigDecimal("1.00")
+  puts transaction.regulatory_fees      # => BigDecimal("0.50")
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies and verify your environment is configured correctly.

data/ROADMAP.md

@@ -24,16 +24,16 @@ This document outlines the development roadmap for the unofficial Tastytrade Rub
 #### Account Operations
 - [x] Fetch account info and balances (closes #6)
 - [x] Get positions
-- [ ] Get transaction history
-- [ ] Calculate buying power
-- [ ] Account status and trading permissions
+- [x] Get transaction history (closes #8)
+- [x] Calculate buying power (closes #9)
+- [x] Account status and trading permissions (closes #10)
 
 #### Basic Trading
-- [ ] Place equity orders (market, limit)
-- [ ] Cancel/replace orders
-- [ ] Get order status
-- [ ] Order validation
-- [ ] Basic order types (day, GTC)
+- [x] Place equity orders (market, limit) (closes #11)
+- [x] Cancel/replace orders (closes #12)
+- [x] Get order status (closes #13)
+- [x] Order validation (closes #14)
+- [x] Basic order types (day, GTC) (closes #15)
 
 #### Core Infrastructure
 - [x] HTTP client setup (Faraday) (closes #16)
@@ -77,11 +77,11 @@ This document outlines the development roadmap for the unofficial Tastytrade Rub
 **Target: Q1 2026 (January - March)**
 
 #### Core CLI Commands
-- [ ] Authentication (`tt login`)
-- [ ] Account info (`tt account`)
-- [ ] Portfolio view (`tt portfolio`)
-- [ ] Basic trading (`tt trade`)
-- [ ] Order management (`tt orders`)
+- [x] Authentication (`tt login`)
+- [x] Account info (`tt account`)
+- [x] Portfolio view (`tt portfolio`)
+- [x] Basic trading (`tt trade`)
+- [x] Order management (`tt orders`)
 
 #### Options CLI
 - [ ] Option chains (`tt option chain`)
@@ -94,13 +94,13 @@ This document outlines the development roadmap for the unofficial Tastytrade Rub
 - [ ] Portfolio analysis (`tt analyze`)
 - [ ] Real-time quotes (`tt quote`)
 - [ ] Configuration management (`tt config`)
-- [ ] Interactive mode
+- [x] Interactive mode
 
 #### CLI Enhancements
-- [ ] Rich terminal output (TTY gems)
+- [x] Rich terminal output (TTY gems)
 - [ ] Progress indicators
-- [ ] Confirmation prompts
-- [ ] Output formatting (JSON, CSV, table)
+- [x] Confirmation prompts
+- [x] Output formatting (JSON, CSV, table)
 - [ ] Shell completion
 
 ### Phase 4: Advanced Features & Polish