tastytrade 0.2.0 → 0.3.0

data/lib/tastytrade/models/transaction.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "bigdecimal"
+
+module Tastytrade
+  module Models
+    # Represents a transaction in a Tastytrade account
+    class Transaction < Base
+      attr_reader :id, :account_number, :symbol, :instrument_type, :underlying_symbol,
+                  :transaction_type, :transaction_sub_type, :description, :action,
+                  :quantity, :price, :executed_at, :transaction_date, :value,
+                  :value_effect, :net_value, :net_value_effect, :is_estimated_fee,
+                  :commission, :clearing_fees, :regulatory_fees, :proprietary_index_option_fees,
+                  :order_id, :value_date, :reverses_id, :is_verified
+
+      TRANSACTION_TYPES = %w[
+        ACAT Assignment Balance\ Adjustment Cash\ Disbursement Cash\ Merger
+        Cash\ Settled\ Assignment Cash\ Settled\ Exercise Credit\ Interest
+        Debit\ Interest Deposit Dividend Exercise Expiration Fee Forward\ Split
+        Futures\ Settlement Journal\ Entry Mark\ to\ Market Maturity
+        Merger\ Acquisition Money\ Movement Name\ Change
+        Paid\ Premium\ Lending\ Income Receive\ Deliver Reverse\ Split
+        Special\ Dividend Stock\ Dividend Stock\ Loan\ Income Stock\ Merger
+        Symbol\ Change Transfer Withdrawal
+      ].freeze
+
+      INSTRUMENT_TYPES = %w[
+        Bond Cryptocurrency Equity Equity\ Offering Equity\ Option Future
+        Future\ Option Index Unknown Warrant
+      ].freeze
+
+      # Fetch transaction history for an account
+      # @param session [Tastytrade::Session] Active session
+      # @param account_number [String] Account number
+      # @param options [Hash] Optional filters
+      # @option options [Date, String] :start_date Start date for transactions
+      # @option options [Date, String] :end_date End date for transactions
+      # @option options [String] :symbol Filter by symbol
+      # @option options [String] :underlying_symbol Filter by underlying symbol
+      # @option options [String] :instrument_type Filter by instrument type
+      # @option options [Array<String>] :transaction_types Filter by transaction types
+      # @option options [Integer] :per_page Number of results per page (default: 250)
+      # @option options [Integer] :page_offset Page offset for pagination
+      # @return [Array<Transaction>] Array of transactions
+      def self.get_all(session, account_number, **options)
+        params = build_params(options)
+        transactions = []
+        page_offset = options[:page_offset] || 0
+
+        loop do
+          current_params = params.dup
+          current_params["page-offset"] = page_offset unless page_offset.zero?
+          response = session.get("/accounts/#{account_number}/transactions", current_params)
+
+          items = response.dig("data", "items") || []
+          break if items.empty?
+
+          transactions.concat(items.map { |item| new(item) })
+
+          # Break if we've reached the requested limit or if pagination is manual
+          break if options[:page_offset] || transactions.size >= (options[:per_page] || 250)
+
+          page_offset += 1
+        end
+
+        transactions
+      end
+
+      private
+
+      def parse_attributes
+        parse_data(@data)
+      end
+
+      def self.build_params(options)
+        {}.tap do |params|
+          params["start-date"] = format_date(options[:start_date]) if options[:start_date]
+          params["end-date"] = format_date(options[:end_date]) if options[:end_date]
+          params["symbol"] = options[:symbol] if options[:symbol]
+          params["underlying-symbol"] = options[:underlying_symbol] if options[:underlying_symbol]
+          params["instrument-type"] = options[:instrument_type] if options[:instrument_type]
+          params["type[]"] = Array(options[:transaction_types]) if options[:transaction_types]
+          params["per-page"] = options[:per_page] if options[:per_page]
+        end
+      end
+
+      def self.format_date(date)
+        case date
+        when String
+          date
+        when Date, DateTime, Time
+          date.strftime("%Y-%m-%d")
+        else
+          date.to_s
+        end
+      end
+
+      def parse_data(data)
+        @id = data["id"]
+        @account_number = data["account-number"]
+        @symbol = data["symbol"]
+        @instrument_type = data["instrument-type"]
+        @underlying_symbol = data["underlying-symbol"]
+        @transaction_type = data["transaction-type"]
+        @transaction_sub_type = data["transaction-sub-type"]
+        @description = data["description"]
+        @action = data["action"]
+        @quantity = parse_decimal(data["quantity"])
+        @price = parse_decimal(data["price"])
+        @executed_at = parse_datetime(data["executed-at"])
+        @transaction_date = parse_date(data["transaction-date"])
+        @value = parse_decimal(data["value"])
+        @value_effect = data["value-effect"]
+        @net_value = parse_decimal(data["net-value"])
+        @net_value_effect = data["net-value-effect"]
+        @is_estimated_fee = data["is-estimated-fee"]
+        @commission = parse_decimal(data["commission"])
+        @clearing_fees = parse_decimal(data["clearing-fees"])
+        @regulatory_fees = parse_decimal(data["regulatory-fees"])
+        @proprietary_index_option_fees = parse_decimal(data["proprietary-index-option-fees"])
+        @order_id = data["order-id"]
+        @value_date = parse_date(data["value-date"])
+        @reverses_id = data["reverses-id"]
+        @is_verified = data["is-verified"]
+      end
+
+      def parse_decimal(value)
+        return nil if value.nil? || value.to_s.empty?
+        BigDecimal(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_datetime(value)
+        return nil if value.nil? || value.to_s.empty?
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_date(value)
+        return nil if value.nil? || value.to_s.empty?
+        Date.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/tastytrade/models.rb

@@ -5,3 +5,9 @@ require_relative "models/user"
 require_relative "models/account"
 require_relative "models/account_balance"
 require_relative "models/current_position"
+require_relative "models/order_response"
+require_relative "models/live_order"
+require_relative "models/order_status"
+require_relative "models/transaction"
+require_relative "models/buying_power_effect"
+require_relative "models/trading_status"

data/lib/tastytrade/order.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Tastytrade
+  # Order action constants
+  module OrderAction
+    BUY_TO_OPEN = "Buy to Open"
+    SELL_TO_CLOSE = "Sell to Close"
+    SELL_TO_OPEN = "Sell to Open"
+    BUY_TO_CLOSE = "Buy to Close"
+  end
+
+  # Order type constants
+  module OrderType
+    MARKET = "Market"
+    LIMIT = "Limit"
+    STOP = "Stop"
+  end
+
+  # Order time in force constants
+  module OrderTimeInForce
+    DAY = "Day"
+    GTC = "GTC"
+  end
+
+  # Price effect constants
+  module PriceEffect
+    DEBIT = "Debit"
+    CREDIT = "Credit"
+  end
+
+  # Represents a single leg of an order
+  class OrderLeg
+    attr_reader :action, :symbol, :quantity, :instrument_type
+
+    def initialize(action:, symbol:, quantity:, instrument_type: "Equity")
+      validate_action!(action)
+
+      @action = action
+      @symbol = symbol
+      @quantity = quantity.to_i
+      @instrument_type = instrument_type
+    end
+
+    def to_api_params
+      {
+        "action" => @action,
+        "symbol" => @symbol,
+        "quantity" => @quantity,
+        "instrument-type" => @instrument_type
+      }
+    end
+
+    private
+
+    def validate_action!(action)
+      valid_actions = [
+        OrderAction::BUY_TO_OPEN,
+        OrderAction::SELL_TO_CLOSE,
+        OrderAction::SELL_TO_OPEN,
+        OrderAction::BUY_TO_CLOSE
+      ]
+
+      unless valid_actions.include?(action)
+        raise ArgumentError, "Invalid action: #{action}. Must be one of: #{valid_actions.join(", ")}"
+      end
+    end
+  end
+
+  # Represents an order to be placed
+  class Order
+    attr_reader :type, :time_in_force, :legs, :price
+
+    def initialize(type:, time_in_force: OrderTimeInForce::DAY, legs:, price: nil)
+      validate_type!(type)
+      validate_time_in_force!(time_in_force)
+      validate_price!(type, price)
+
+      @type = type
+      @time_in_force = time_in_force
+      @legs = Array(legs)
+      @price = price ? BigDecimal(price.to_s) : nil
+    end
+
+    def market?
+      @type == OrderType::MARKET
+    end
+
+    def limit?
+      @type == OrderType::LIMIT
+    end
+
+    def stop?
+      @type == OrderType::STOP
+    end
+
+    # Validates this order for a specific account using the OrderValidator.
+    # Performs comprehensive checks including symbol existence, quantity constraints,
+    # price validation, account permissions, and optionally buying power.
+    #
+    # @param session [Tastytrade::Session] Active session
+    # @param account [Tastytrade::Models::Account] Account to validate against
+    # @param skip_dry_run [Boolean] Skip dry-run validation for performance
+    # @return [Boolean] true if valid
+    # @raise [OrderValidationError] if validation fails with detailed error messages
+    #
+    # @example
+    #   order.validate!(session, account)  # Full validation including dry-run
+    #   order.validate!(session, account, skip_dry_run: true)  # Skip buying power check
+    def validate!(session, account, skip_dry_run: false)
+      validator = OrderValidator.new(session, account, self)
+      validator.validate!(skip_dry_run: skip_dry_run)
+    end
+
+    # Performs a dry-run validation of the order. This submits the order to the API
+    # in dry-run mode to check buying power, margin requirements, and get warnings
+    # without actually placing the order.
+    #
+    # @param session [Tastytrade::Session] Active session
+    # @param account [Tastytrade::Models::Account] Account to validate against
+    # @return [Tastytrade::Models::OrderResponse] Dry-run response with buying power effect
+    #
+    # @example
+    #   response = order.dry_run(session, account)
+    #   puts response.buying_power_effect
+    #   puts response.warnings
+    def dry_run(session, account)
+      account.place_order(session, self, dry_run: true)
+    end
+
+    def to_api_params
+      params = {
+        "order-type" => @type,
+        "time-in-force" => @time_in_force,
+        "legs" => @legs.map(&:to_api_params)
+      }
+
+      # Add price for limit orders
+      # API expects string representation without negative sign
+      if limit? && @price
+        params["price"] = @price.to_s("F")
+        params["price-effect"] = determine_price_effect
+      end
+
+      params
+    end
+
+    private
+
+    def determine_price_effect
+      # Determine price effect based on the first leg's action
+      # Buy actions result in debit, sell actions result in credit
+      first_leg = @legs.first
+      return PriceEffect::DEBIT unless first_leg
+
+      case first_leg.action
+      when OrderAction::BUY_TO_OPEN, OrderAction::BUY_TO_CLOSE
+        PriceEffect::DEBIT
+      when OrderAction::SELL_TO_OPEN, OrderAction::SELL_TO_CLOSE
+        PriceEffect::CREDIT
+      else
+        PriceEffect::DEBIT # Default to debit
+      end
+    end
+
+    def validate_type!(type)
+      valid_types = [OrderType::MARKET, OrderType::LIMIT, OrderType::STOP]
+      unless valid_types.include?(type)
+        raise ArgumentError, "Invalid order type: #{type}. Must be one of: #{valid_types.join(", ")}"
+      end
+    end
+
+    def validate_time_in_force!(time_in_force)
+      valid_tifs = [OrderTimeInForce::DAY, OrderTimeInForce::GTC]
+      unless valid_tifs.include?(time_in_force)
+        raise ArgumentError, "Invalid time in force: #{time_in_force}. Must be one of: #{valid_tifs.join(", ")}"
+      end
+    end
+
+    def validate_price!(type, price)
+      if type == OrderType::LIMIT && price.nil?
+        raise ArgumentError, "Price is required for limit orders"
+      end
+
+      if price && price.to_f <= 0
+        raise ArgumentError, "Price must be greater than 0"
+      end
+    end
+  end
+end

data/lib/tastytrade/order_validator.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "time"
+
+module Tastytrade
+  # Validates orders before submission to ensure they meet all requirements.
+  # Performs comprehensive checks including symbol validation, quantity constraints,
+  # price validation, account permissions, buying power, and market hours.
+  #
+  # @example Basic usage
+  #   validator = OrderValidator.new(session, account, order)
+  #   validator.validate! # Raises OrderValidationError if invalid
+  #
+  # @example With dry-run validation
+  #   validator = OrderValidator.new(session, account, order)
+  #   response = validator.dry_run_validate!
+  #   puts validator.warnings if validator.warnings.any?
+  class OrderValidator
+    # @return [Array<String>] List of validation errors
+    attr_reader :errors
+
+    # @return [Array<String>] List of validation warnings
+    attr_reader :warnings
+
+    # Common tick sizes for different price ranges
+    TICK_SIZES = {
+      penny: BigDecimal("0.01"),
+      nickel: BigDecimal("0.05"),
+      dime: BigDecimal("0.10")
+    }.freeze
+
+    # Minimum quantity constraints
+    MIN_QUANTITY = 1
+    MAX_QUANTITY = 999_999
+
+    # Creates a new OrderValidator instance
+    #
+    # @param session [Tastytrade::Session] Active trading session
+    # @param account [Tastytrade::Models::Account] Account to validate against
+    # @param order [Tastytrade::Order] Order to validate
+    def initialize(session, account, order)
+      @session = session
+      @account = account
+      @order = order
+      @errors = []
+      @warnings = []
+      @trading_status = nil
+      @dry_run_response = nil
+    end
+
+    # Performs comprehensive order validation including structure, symbols,
+    # quantities, prices, account permissions, market hours, and optionally
+    # buying power via dry-run.
+    #
+    # @param skip_dry_run [Boolean] Skip the dry-run validation (for performance)
+    # @return [Boolean] true if validation passes
+    # @raise [OrderValidationError] if validation fails with detailed error messages
+    def validate!(skip_dry_run: false)
+      # Reset errors and warnings
+      @errors = []
+      @warnings = []
+
+      # Run all validations
+      validate_order_structure!
+      validate_symbols!
+      validate_quantities!
+      validate_prices!
+      validate_account_permissions!
+      validate_market_hours!
+      validate_buying_power! unless skip_dry_run
+
+      # Raise error if any validation failed
+      raise OrderValidationError, @errors if @errors.any?
+
+      true
+    end
+
+    # Performs pre-flight validation via dry-run API call. This checks buying power,
+    # margin requirements, and API-level validation rules without placing the order.
+    #
+    # @return [Tastytrade::Models::OrderResponse, nil] Dry-run response if successful, nil if failed
+    def dry_run_validate!
+      @dry_run_response = @account.place_order(@session, @order, dry_run: true)
+
+      # Check for API-level errors
+      if @dry_run_response.errors.any?
+        @errors.concat(@dry_run_response.errors.map { |e| format_api_error(e) })
+      end
+
+      # Check for warnings
+      if @dry_run_response.warnings.any?
+        @warnings.concat(@dry_run_response.warnings)
+      end
+
+      # Check buying power effect
+      if @dry_run_response.buying_power_effect
+        validate_buying_power_effect!(@dry_run_response.buying_power_effect)
+      end
+
+      @dry_run_response
+    rescue StandardError => e
+      @errors << "Dry-run validation failed: #{e.message}"
+      nil
+    end
+
+    private
+
+    # Validate basic order structure
+    def validate_order_structure!
+      # Check for at least one leg
+      if @order.legs.nil? || @order.legs.empty?
+        @errors << "Order must have at least one leg"
+      end
+
+      # Validate order type and price consistency
+      if @order.limit? && @order.price.nil?
+        @errors << "Limit orders require a price"
+      end
+
+      # Validate time in force
+      if @order.time_in_force.nil?
+        @errors << "Time in force is required"
+      end
+    end
+
+    # Validate symbols exist and are tradeable
+    def validate_symbols!
+      return if @order.legs.nil?
+
+      @order.legs.each do |leg|
+        validate_symbol!(leg.symbol, leg.instrument_type)
+      end
+    end
+
+    # Validate a single symbol
+    def validate_symbol!(symbol, instrument_type)
+      return if symbol.nil? || symbol.empty?
+
+      case instrument_type
+      when "Equity"
+        validate_equity_symbol!(symbol)
+      when "Option"
+        # TODO: Implement option symbol validation
+        @warnings << "Option symbol validation not yet implemented for #{symbol}"
+      when "Future"
+        # TODO: Implement futures symbol validation
+        @warnings << "Futures symbol validation not yet implemented for #{symbol}"
+      else
+        @errors << "Unknown instrument type: #{instrument_type}"
+      end
+    end
+
+    # Validate equity symbol exists
+    def validate_equity_symbol!(symbol)
+      # Try to fetch the equity to validate it exists
+      Instruments::Equity.get(@session, symbol)
+    rescue StandardError => e
+      @errors << "Invalid equity symbol '#{symbol}': #{e.message}"
+    end
+
+    # Validate order quantities
+    def validate_quantities!
+      return if @order.legs.nil?
+
+      @order.legs.each do |leg|
+        validate_quantity!(leg.quantity, leg.symbol)
+      end
+    end
+
+    # Validate a single quantity
+    def validate_quantity!(quantity, symbol)
+      # Check minimum quantity
+      if quantity.nil? || quantity < MIN_QUANTITY
+        @errors << "Quantity for #{symbol} must be at least #{MIN_QUANTITY}"
+      end
+
+      # Check maximum quantity
+      if quantity && quantity > MAX_QUANTITY
+        @errors << "Quantity for #{symbol} exceeds maximum of #{MAX_QUANTITY}"
+      end
+
+      # Check for whole shares (no fractional shares for now)
+      if quantity && quantity != quantity.to_i
+        @errors << "Fractional shares not supported for #{symbol}"
+      end
+    end
+
+    # Validate order prices
+    def validate_prices!
+      return unless @order.limit?
+
+      validate_price!(@order.price)
+    end
+
+    # Validate a single price
+    def validate_price!(price)
+      return if price.nil?
+
+      # Check for positive price
+      if price <= 0
+        @errors << "Price must be greater than 0"
+      end
+
+      # Check for reasonable price (not too high)
+      if price > BigDecimal("999999")
+        @errors << "Price exceeds reasonable limits"
+      end
+
+      # Round to appropriate tick size
+      rounded_price = round_to_tick_size(price)
+      if rounded_price != price
+        @warnings << "Price #{price} will be rounded to #{rounded_price}"
+      end
+    end
+
+    # Round price to appropriate tick size
+    def round_to_tick_size(price)
+      return price if price.nil?
+
+      # Simple tick size rules (can be enhanced based on instrument/exchange)
+      tick = if price < BigDecimal("1")
+        TICK_SIZES[:penny]
+      elsif price < BigDecimal("10")
+        TICK_SIZES[:penny]
+      else
+        TICK_SIZES[:penny]
+      end
+
+      (price / tick).round * tick
+    end
+
+    # Validate account permissions for the order
+    def validate_account_permissions!
+      @trading_status ||= @account.get_trading_status(@session)
+
+      # Check if account is restricted
+      if @trading_status.restricted?
+        restrictions = @trading_status.active_restrictions
+        @errors << "Account has active restrictions: #{restrictions.join(", ")}"
+      end
+
+      # Check specific permissions based on order type
+      @order.legs.each do |leg|
+        validate_leg_permissions!(leg)
+      end
+    end
+
+    # Validate permissions for a specific leg
+    def validate_leg_permissions!(leg)
+      @trading_status ||= @account.get_trading_status(@session)
+
+      case leg.instrument_type
+      when "Option"
+        unless @trading_status.can_trade_options?
+          @errors << "Account does not have options trading permissions"
+        end
+      when "Future"
+        unless @trading_status.can_trade_futures?
+          @errors << "Account does not have futures trading permissions"
+        end
+      when "Cryptocurrency"
+        unless @trading_status.can_trade_cryptocurrency?
+          @errors << "Account does not have cryptocurrency trading permissions"
+        end
+      end
+
+      # Check for closing-only restrictions
+      if opening_order?(leg.action) && @trading_status.is_closing_only
+        @errors << "Account is restricted to closing orders only"
+      end
+    end
+
+    # Check if this is an opening order
+    def opening_order?(action)
+      [OrderAction::BUY_TO_OPEN, OrderAction::SELL_TO_OPEN].include?(action)
+    end
+
+    # Validate market hours
+    def validate_market_hours!
+      # Get current time
+      now = Time.now
+
+      # Check if it's a market order during extended hours
+      if @order.market? && !regular_market_hours?(now)
+        @warnings << "Market orders may not be accepted outside regular trading hours"
+      end
+
+      # Basic weekday/weekend check
+      if weekend?(now)
+        @warnings << "Markets are closed on weekends"
+      end
+    end
+
+    # Check if current time is during regular market hours (9:30 AM - 4:00 PM ET)
+    def regular_market_hours?(time)
+      # Convert to Eastern Time (simplified - should use proper timezone library)
+      hour = time.hour
+      minute = time.min
+
+      # Rough check for market hours (9:30 AM - 4:00 PM ET)
+      # Note: This is simplified and doesn't account for timezones properly
+      return false if hour < 9 || hour >= 16
+      return false if hour == 9 && minute < 30
+
+      true
+    end
+
+    # Check if it's a weekend
+    def weekend?(time)
+      time.saturday? || time.sunday?
+    end
+
+    # Validate buying power via dry-run
+    def validate_buying_power!
+      # If we haven't run dry-run yet, do it now
+      @dry_run_response ||= dry_run_validate!
+      return if @dry_run_response.nil?
+
+      effect = @dry_run_response.buying_power_effect
+      return if effect.nil?
+
+      validate_buying_power_effect!(effect)
+    end
+
+    # Validate buying power effect from dry-run
+    def validate_buying_power_effect!(effect)
+      # Check if order would result in negative buying power
+      if effect.new_buying_power && effect.new_buying_power < 0
+        @errors << "Insufficient buying power. Order requires #{effect.buying_power_change_amount}, " \
+                   "but only #{effect.current_buying_power} available"
+      end
+
+      # Warn if using significant portion of buying power
+      if effect.buying_power_usage_percentage > BigDecimal("50")
+        percentage = effect.buying_power_usage_percentage.to_f.round(1)
+        @warnings << "Order will use #{percentage}% of available buying power"
+      end
+
+      # Check for margin requirements
+      if effect.change_in_margin_requirement && effect.change_in_margin_requirement.abs > effect.current_buying_power
+        @errors << "Margin requirement of #{effect.change_in_margin_requirement.abs} exceeds available buying power"
+      end
+    end
+
+    # Format API error for display
+    def format_api_error(error)
+      if error.is_a?(Hash)
+        "#{error["domain"]}: #{error["reason"]}"
+      else
+        error.to_s
+      end
+    end
+  end
+end