DhanHQ 2.1.3 → 2.1.6

data/lib/DhanHQ/models/expired_options_data.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Represents expired options data for rolling contracts
+    # Provides access to OHLC, volume, open interest, implied volatility, and spot data
+    # rubocop:disable Metrics/ClassLength
+    class ExpiredOptionsData < BaseModel
+      # All expired options data attributes
+      attributes :exchange_segment, :interval, :security_id, :instrument,
+                 :expiry_flag, :expiry_code, :strike, :drv_option_type,
+                 :required_data, :from_date, :to_date, :data
+
+      class << self
+        ##
+        # Fetch expired options data for rolling contracts
+        # POST /charts/rollingoption
+        #
+        # @param params [Hash] Parameters for the request
+        # @option params [String] :exchange_segment Exchange segment (e.g., "NSE_FNO")
+        # @option params [Integer] :interval Minute interval (1, 5, 15, 25, 60)
+        # @option params [String] :security_id Security ID for the underlying
+        # @option params [String] :instrument Instrument type ("OPTIDX" or "OPTSTK")
+        # @option params [String] :expiry_flag Expiry interval ("WEEK" or "MONTH")
+        # @option params [Integer] :expiry_code Expiry code
+        # @option params [String] :strike Strike price ("ATM", "ATM+1", "ATM-1", etc.)
+        # @option params [String] :drv_option_type Option type ("CALL" or "PUT")
+        # @option params [Array<String>] :required_data Required data fields
+        # @option params [String] :from_date Start date (YYYY-MM-DD)
+        # @option params [String] :to_date End date (YYYY-MM-DD)
+        # @return [ExpiredOptionsData] Expired options data object
+        def fetch(params)
+          validate_params(params)
+
+          response = expired_options_resource.fetch(params)
+          new(response.merge(params), skip_validation: true)
+        end
+
+        private
+
+        def expired_options_resource
+          @expired_options_resource ||= DhanHQ::Resources::ExpiredOptionsData.new
+        end
+
+        def validate_params(params)
+          contract = DhanHQ::Contracts::ExpiredOptionsDataContract.new
+          validation_result = contract.call(params)
+
+          return if validation_result.success?
+
+          raise DhanHQ::ValidationError, "Invalid parameters: #{validation_result.errors.to_h}"
+        end
+      end
+
+      ##
+      # ExpiredOptionsData objects are read-only, so no validation contract needed
+      def validation_contract
+        nil
+      end
+
+      ##
+      # Get call option data
+      # @return [Hash, nil] Call option data or nil if not available
+      def call_data
+        return nil unless data.is_a?(Hash)
+
+        data["ce"] || data[:ce]
+      end
+
+      ##
+      # Get put option data
+      # @return [Hash, nil] Put option data or nil if not available
+      def put_data
+        return nil unless data.is_a?(Hash)
+
+        data["pe"] || data[:pe]
+      end
+
+      ##
+      # Get data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Hash, nil] Option data or nil if not available
+      def data_for_type(option_type)
+        case option_type.upcase
+        when "CALL"
+          call_data
+        when "PUT"
+          put_data
+        end
+      end
+
+      ##
+      # Get OHLC data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Hash] OHLC data with open, high, low, close arrays
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def ohlc_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return {} unless option_data
+
+        {
+          open: option_data["open"] || option_data[:open] || [],
+          high: option_data["high"] || option_data[:high] || [],
+          low: option_data["low"] || option_data[:low] || [],
+          close: option_data["close"] || option_data[:close] || []
+        }
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      ##
+      # Get volume data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Integer>] Volume data array
+      def volume_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return [] unless option_data
+
+        option_data["volume"] || option_data[:volume] || []
+      end
+
+      ##
+      # Get open interest data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Float>] Open interest data array
+      def open_interest_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return [] unless option_data
+
+        option_data["oi"] || option_data[:oi] || []
+      end
+
+      ##
+      # Get implied volatility data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Float>] Implied volatility data array
+      def implied_volatility_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return [] unless option_data
+
+        option_data["iv"] || option_data[:iv] || []
+      end
+
+      ##
+      # Get strike price data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Float>] Strike price data array
+      def strike_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return [] unless option_data
+
+        option_data["strike"] || option_data[:strike] || []
+      end
+
+      ##
+      # Get spot price data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Float>] Spot price data array
+      def spot_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return [] unless option_data
+
+        option_data["spot"] || option_data[:spot] || []
+      end
+
+      ##
+      # Get timestamp data for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Integer>] Timestamp data array (epoch)
+      def timestamp_data(option_type = nil)
+        option_type ||= drv_option_type
+        option_data = data_for_type(option_type)
+        return [] unless option_data
+
+        option_data["timestamp"] || option_data[:timestamp] || []
+      end
+
+      ##
+      # Get data points count for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Integer] Number of data points
+      def data_points_count(option_type = nil)
+        timestamps = timestamp_data(option_type)
+        timestamps.size
+      end
+
+      ##
+      # Get average volume for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Float] Average volume
+      def average_volume(option_type = nil)
+        volumes = volume_data(option_type)
+        return 0.0 if volumes.empty?
+
+        volumes.sum.to_f / volumes.size
+      end
+
+      ##
+      # Get average open interest for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Float] Average open interest
+      def average_open_interest(option_type = nil)
+        oi_data = open_interest_data(option_type)
+        return 0.0 if oi_data.empty?
+
+        oi_data.sum.to_f / oi_data.size
+      end
+
+      ##
+      # Get average implied volatility for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Float] Average implied volatility
+      def average_implied_volatility(option_type = nil)
+        iv_data = implied_volatility_data(option_type)
+        return 0.0 if iv_data.empty?
+
+        iv_data.sum.to_f / iv_data.size
+      end
+
+      ##
+      # Get price range (high - low) for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Array<Float>] Price range for each data point
+      def price_ranges(option_type = nil)
+        ohlc = ohlc_data(option_type)
+        highs = ohlc[:high]
+        lows = ohlc[:low]
+
+        return [] if highs.empty? || lows.empty?
+
+        highs.zip(lows).map { |high, low| high - low }
+      end
+
+      ##
+      # Get summary statistics for the specified option type
+      # @param option_type [String] "CALL" or "PUT"
+      # @return [Hash] Summary statistics
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def summary_stats(option_type = nil)
+        option_type ||= drv_option_type
+        ohlc = ohlc_data(option_type)
+        volumes = volume_data(option_type)
+        oi_data = open_interest_data(option_type)
+        iv_data = implied_volatility_data(option_type)
+
+        {
+          data_points: data_points_count(option_type),
+          avg_volume: average_volume(option_type),
+          avg_open_interest: average_open_interest(option_type),
+          avg_implied_volatility: average_implied_volatility(option_type),
+          price_ranges: price_ranges(option_type),
+          has_ohlc: !ohlc[:open].empty?,
+          has_volume: !volumes.empty?,
+          has_open_interest: !oi_data.empty?,
+          has_implied_volatility: !iv_data.empty?
+        }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      ##
+      # Check if this is index options data
+      # @return [Boolean] true if instrument is OPTIDX
+      def index_options?
+        instrument == "OPTIDX"
+      end
+
+      ##
+      # Check if this is stock options data
+      # @return [Boolean] true if instrument is OPTSTK
+      def stock_options?
+        instrument == "OPTSTK"
+      end
+
+      ##
+      # Check if this is weekly expiry
+      # @return [Boolean] true if expiry_flag is WEEK
+      def weekly_expiry?
+        expiry_flag == "WEEK"
+      end
+
+      ##
+      # Check if this is monthly expiry
+      # @return [Boolean] true if expiry_flag is MONTH
+      def monthly_expiry?
+        expiry_flag == "MONTH"
+      end
+
+      ##
+      # Check if this is call option data
+      # @return [Boolean] true if drv_option_type is CALL
+      def call_option?
+        drv_option_type == "CALL"
+      end
+
+      ##
+      # Check if this is put option data
+      # @return [Boolean] true if drv_option_type is PUT
+      def put_option?
+        drv_option_type == "PUT"
+      end
+
+      ##
+      # Check if strike is at the money
+      # @return [Boolean] true if strike is ATM
+      def at_the_money?
+        strike == "ATM"
+      end
+
+      ##
+      # Get strike offset from ATM
+      # @return [Integer] Strike offset (0 for ATM, positive for ATM+X, negative for ATM-X)
+      def strike_offset
+        return 0 if at_the_money?
+
+        match = strike.match(/\AATM(\+|-)?(\d+)\z/)
+        return 0 unless match
+
+        sign = match[1] == "-" ? -1 : 1
+        offset = match[2].to_i
+        sign * offset
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/DhanHQ/models/instrument.rb

@@ -7,7 +7,10 @@ module DhanHQ
     # Model wrapper for fetching instruments by exchange segment.
     class Instrument < BaseModel
       attributes :security_id, :symbol_name, :display_name, :exchange_segment, :instrument, :series,
-                 :lot_size, :tick_size, :expiry_date, :strike_price, :option_type
+                 :lot_size, :tick_size, :expiry_date, :strike_price, :option_type, :underlying_symbol,
+                 :isin, :instrument_type, :expiry_flag, :bracket_flag, :cover_flag, :asm_gsm_flag,
+                 :asm_gsm_category, :buy_sell_indicator, :buy_co_min_margin_per, :sell_co_min_margin_per,
+                 :mtf_leverage
 
       class << self
         # @return [DhanHQ::Resources::Instruments]
@@ -29,6 +32,85 @@ module DhanHQ
           rows.map { |r| new(normalize_csv_row(r), skip_validation: true) }
         end
 
+        # Find a specific instrument by exchange segment and symbol.
+        # @param exchange_segment [String] The exchange segment (e.g., "NSE_EQ", "IDX_I")
+        # @param symbol [String] The symbol name to search for
+        # @param options [Hash] Additional search options
+        # @option options [Boolean] :exact_match Whether to perform exact symbol matching (default: false)
+        # @option options [Boolean] :case_sensitive Whether the search should be case sensitive (default: false)
+        # @return [Instrument, nil] The found instrument or nil if not found
+        # @example
+        #   # Find RELIANCE in NSE_EQ (uses underlying_symbol for equity)
+        #   instrument = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+        #   puts instrument.security_id  # => "2885"
+        #
+        #   # Find NIFTY in IDX_I (uses symbol_name for indices)
+        #   instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+        #   puts instrument.security_id  # => "13"
+        #
+        #   # Exact match search
+        #   instrument = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE", exact_match: true)
+        #
+        #   # Case sensitive search
+        #   instrument = DhanHQ::Models::Instrument.find("NSE_EQ", "reliance", case_sensitive: true)
+        def find(exchange_segment, symbol, options = { exact_match: true, case_sensitive: false })
+          validate_params!({ exchange_segment: exchange_segment, symbol: symbol }, DhanHQ::Contracts::InstrumentListContract)
+
+          exact_match = options[:exact_match] || false
+          case_sensitive = options[:case_sensitive] || false
+
+          instruments = by_segment(exchange_segment)
+          return nil if instruments.empty?
+
+          search_symbol = case_sensitive ? symbol : symbol.upcase
+
+          instruments.find do |instrument|
+            # For equity instruments, prefer underlying_symbol over symbol_name
+            instrument_symbol = if instrument.instrument == "EQUITY" && instrument.underlying_symbol
+                                  case_sensitive ? instrument.underlying_symbol : instrument.underlying_symbol.upcase
+                                else
+                                  case_sensitive ? instrument.symbol_name : instrument.symbol_name.upcase
+                                end
+
+            if exact_match
+              instrument_symbol == search_symbol
+            else
+              instrument_symbol.include?(search_symbol)
+            end
+          end
+        end
+
+        # Find a specific instrument across all exchange segments.
+        # @param symbol [String] The symbol name to search for
+        # @param options [Hash] Additional search options
+        # @option options [Boolean] :exact_match Whether to perform exact symbol matching (default: false)
+        # @option options [Boolean] :case_sensitive Whether the search should be case sensitive (default: false)
+        # @option options [Array<String>] :segments Specific segments to search in (default: all common segments)
+        # @return [Instrument, nil] The found instrument or nil if not found
+        # @example
+        #   # Find RELIANCE across all segments
+        #   instrument = DhanHQ::Models::Instrument.find_anywhere("RELIANCE")
+        #   puts "#{instrument.exchange_segment}:#{instrument.security_id}"  # => "NSE_EQ:2885"
+        #
+        #   # Find NIFTY across all segments
+        #   instrument = DhanHQ::Models::Instrument.find_anywhere("NIFTY")
+        #   puts "#{instrument.exchange_segment}:#{instrument.security_id}"  # => "IDX_I:13"
+        #
+        #   # Search only in specific segments
+        #   instrument = DhanHQ::Models::Instrument.find_anywhere("RELIANCE", segments: ["NSE_EQ", "BSE_EQ"])
+        def find_anywhere(symbol, options = {})
+          exact_match = options[:exact_match] || false
+          case_sensitive = options[:case_sensitive] || false
+          segments = options[:segments] || %w[NSE_EQ BSE_EQ IDX_I NSE_FNO NSE_CURRENCY]
+
+          segments.each do |segment|
+            instrument = find(segment, symbol, exact_match: exact_match, case_sensitive: case_sensitive)
+            return instrument if instrument
+          end
+
+          nil
+        end
+
         def normalize_csv_row(row)
           {
             security_id: row["SECURITY_ID"].to_s,
@@ -41,7 +123,19 @@ module DhanHQ
             tick_size: row["TICK_SIZE"]&.to_f,
             expiry_date: row["SM_EXPIRY_DATE"],
             strike_price: row["STRIKE_PRICE"]&.to_f,
-            option_type: row["OPTION_TYPE"]
+            option_type: row["OPTION_TYPE"],
+            underlying_symbol: row["UNDERLYING_SYMBOL"],
+            isin: row["ISIN"],
+            instrument_type: row["INSTRUMENT_TYPE"],
+            expiry_flag: row["EXPIRY_FLAG"],
+            bracket_flag: row["BRACKET_FLAG"],
+            cover_flag: row["COVER_FLAG"],
+            asm_gsm_flag: row["ASM_GSM_FLAG"],
+            asm_gsm_category: row["ASM_GSM_CATEGORY"],
+            buy_sell_indicator: row["BUY_SELL_INDICATOR"],
+            buy_co_min_margin_per: row["BUY_CO_MIN_MARGIN_PER"]&.to_f,
+            sell_co_min_margin_per: row["SELL_CO_MIN_MARGIN_PER"]&.to_f,
+            mtf_leverage: row["MTF_LEVERAGE"]&.to_f
           }
         end
       end

data/lib/DhanHQ/models/option_chain.rb

@@ -34,6 +34,8 @@ module DhanHQ
         # @param params [Hash] The request parameters (snake_case format)
         # @return [Array<String>] The list of expiry dates
         def fetch_expiry_list(params)
+          validate_params!(params, DhanHQ::Contracts::OptionChainExpiryListContract)
+
           response = resource.expirylist(params)
           response[:status] == "success" ? response[:data] : []
         end

data/lib/DhanHQ/models/order_update.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Represents a real-time order update received via WebSocket
+    # Parses and provides access to all order update fields as per DhanHQ API documentation
+    # rubocop:disable Metrics/ClassLength
+    class OrderUpdate < BaseModel
+      # All order update attributes as per API documentation
+      attributes :exchange, :segment, :source, :security_id, :client_id,
+                 :exch_order_no, :order_no, :product, :txn_type, :order_type,
+                 :validity, :disc_quantity, :disc_qty_rem, :remaining_quantity,
+                 :quantity, :traded_qty, :price, :trigger_price, :traded_price,
+                 :avg_traded_price, :algo_ord_no, :off_mkt_flag, :order_date_time,
+                 :exch_order_time, :last_updated_time, :remarks, :mkt_type,
+                 :reason_description, :leg_no, :instrument, :symbol, :product_name,
+                 :status, :lot_size, :strike_price, :expiry_date, :opt_type,
+                 :display_name, :isin, :series, :good_till_days_date, :ref_ltp,
+                 :tick_size, :algo_id, :multiplier, :correlation_id
+
+      ##
+      # Create OrderUpdate from WebSocket message
+      # @param message [Hash] Raw WebSocket message
+      # @return [OrderUpdate] Parsed order update
+      def self.from_websocket_message(message)
+        return nil unless message.is_a?(Hash) && message[:Type] == "order_alert"
+        return nil unless message[:Data].is_a?(Hash)
+
+        # Map the WebSocket message data to our attributes
+        data = message[:Data]
+        new(data, skip_validation: true)
+      end
+
+      ##
+      # OrderUpdate objects are read-only, so no validation contract needed
+      def validation_contract
+        nil
+      end
+
+      ##
+      # Helper methods for transaction type
+      def buy?
+        txn_type == "B"
+      end
+
+      def sell?
+        txn_type == "S"
+      end
+
+      ##
+      # Helper methods for order type
+      def limit_order?
+        order_type == "LMT"
+      end
+
+      def market_order?
+        order_type == "MKT"
+      end
+
+      def stop_loss_order?
+        order_type == "SL"
+      end
+
+      def stop_loss_market_order?
+        order_type == "SLM"
+      end
+
+      ##
+      # Helper methods for product type
+      def cnc_product?
+        product == "C"
+      end
+
+      def intraday_product?
+        product == "I"
+      end
+
+      def margin_product?
+        product == "M"
+      end
+
+      def mtf_product?
+        product == "F"
+      end
+
+      def cover_order?
+        product == "V"
+      end
+
+      def bracket_order?
+        product == "B"
+      end
+
+      ##
+      # Helper methods for order status
+      def transit?
+        status == "TRANSIT"
+      end
+
+      def pending?
+        status == "PENDING"
+      end
+
+      def rejected?
+        status == "REJECTED"
+      end
+
+      def cancelled?
+        status == "CANCELLED"
+      end
+
+      def traded?
+        status == "TRADED"
+      end
+
+      def expired?
+        status == "EXPIRED"
+      end
+
+      ##
+      # Helper methods for instrument type
+      def equity?
+        instrument == "EQUITY"
+      end
+
+      def derivative?
+        instrument == "DERIVATIVES"
+      end
+
+      def option?
+        %w[CE PE].include?(opt_type)
+      end
+
+      def call_option?
+        opt_type == "CE"
+      end
+
+      def put_option?
+        opt_type == "PE"
+      end
+
+      ##
+      # Helper methods for order leg (for Super Orders)
+      def entry_leg?
+        leg_no == 1
+      end
+
+      def stop_loss_leg?
+        leg_no == 2
+      end
+
+      def target_leg?
+        leg_no == 3
+      end
+
+      ##
+      # Helper methods for market type
+      def normal_market?
+        mkt_type == "NL"
+      end
+
+      def auction_market?
+        %w[AU A1 A2].include?(mkt_type)
+      end
+
+      ##
+      # Helper methods for order characteristics
+      def amo_order?
+        off_mkt_flag == "1"
+      end
+
+      def super_order?
+        remarks == "Super Order"
+      end
+
+      def partially_executed?
+        traded_qty.positive? && traded_qty < quantity
+      end
+
+      def fully_executed?
+        traded_qty == quantity
+      end
+
+      def not_executed?
+        traded_qty.zero?
+      end
+
+      ##
+      # Calculation methods
+      def execution_percentage
+        return 0.0 if quantity.zero?
+
+        (traded_qty.to_f / quantity * 100).round(2)
+      end
+
+      def pending_quantity
+        quantity - traded_qty
+      end
+
+      def total_value
+        return 0 unless traded_qty && avg_traded_price
+
+        traded_qty * avg_traded_price
+      end
+
+      ##
+      # Status summary for logging/debugging
+      # rubocop:disable Metrics/MethodLength
+      def status_summary
+        {
+          order_no: order_no,
+          symbol: symbol,
+          status: status,
+          txn_type: txn_type,
+          quantity: quantity,
+          traded_qty: traded_qty,
+          execution_percentage: execution_percentage,
+          price: price,
+          avg_traded_price: avg_traded_price,
+          leg_no: leg_no,
+          super_order: super_order?
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      ##
+      # Convert to hash for serialization
+      def to_hash
+        @attributes.dup
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end