DhanHQ 2.1.5 → 2.1.7

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

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 require_relative "../contracts/instrument_list_contract"
+require_relative "instrument_helpers"
 
 module DhanHQ
   module Models
     # 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
+      include InstrumentHelpers
+
+      attributes :security_id, :symbol_name, :display_name, :exchange, :segment, :exchange_segment, :instrument, :series,
+                 :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,19 +35,123 @@ 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)
+          # Extract exchange and segment from CSV
+          exchange_id = row["EXCH_ID"] || row["EXCHANGE"]
+          segment_code = row["SEGMENT"]
+
+          # Calculate exchange_segment using SEGMENT_MAP from Constants
+          exchange_segment = if exchange_id && segment_code
+                               DhanHQ::Constants::SEGMENT_MAP[[exchange_id, segment_code]]
+                             else
+                               row["EXCH_ID"] # Fallback to original value
+                             end
+
           {
             security_id: row["SECURITY_ID"].to_s,
             symbol_name: row["SYMBOL_NAME"],
             display_name: row["DISPLAY_NAME"],
-            exchange_segment: row["EXCH_ID"],
+            exchange: exchange_id,
+            segment: segment_code,
+            exchange_segment: exchange_segment,
             instrument: row["INSTRUMENT"],
             series: row["SERIES"],
             lot_size: row["LOT_SIZE"]&.to_f,
             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/instrument_helpers.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Helper module providing instance methods for Instrument objects
+    # to access market feed, historical data, and option chain data.
+    module InstrumentHelpers
+      ##
+      # Fetches last traded price (LTP) for this instrument.
+      #
+      # @return [Hash] Market feed LTP response
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+      #   instrument.ltp
+      def ltp
+        params = build_market_feed_params
+        DhanHQ::Models::MarketFeed.ltp(params)
+      end
+
+      ##
+      # Fetches OHLC (Open-High-Low-Close) data for this instrument.
+      #
+      # @return [Hash] Market feed OHLC response
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+      #   instrument.ohlc
+      def ohlc
+        params = build_market_feed_params
+        DhanHQ::Models::MarketFeed.ohlc(params)
+      end
+
+      ##
+      # Fetches full quote depth and analytics for this instrument.
+      #
+      # @return [Hash] Market feed quote response
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("NSE_FNO", "RELIANCE")
+      #   instrument.quote
+      def quote
+        params = build_market_feed_params
+        DhanHQ::Models::MarketFeed.quote(params)
+      end
+
+      ##
+      # Fetches daily historical data for this instrument.
+      #
+      # @param from_date [String] Start date in YYYY-MM-DD format
+      # @param to_date [String] End date in YYYY-MM-DD format
+      # @param options [Hash] Additional options (e.g., expiry_code)
+      # @return [Hash] Historical data with open, high, low, close, volume, timestamp arrays
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+      #   instrument.daily(from_date: "2024-01-01", to_date: "2024-01-31")
+      def daily(from_date:, to_date:, **options)
+        params = build_historical_data_params(from_date: from_date, to_date: to_date, **options)
+        DhanHQ::Models::HistoricalData.daily(params)
+      end
+
+      ##
+      # Fetches intraday historical data for this instrument.
+      #
+      # @param from_date [String] Start date in YYYY-MM-DD format
+      # @param to_date [String] End date in YYYY-MM-DD format
+      # @param interval [String] Time interval in minutes (1, 5, 15, 25, 60)
+      # @param options [Hash] Additional options
+      # @return [Hash] Historical data with open, high, low, close, volume, timestamp arrays
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+      #   instrument.intraday(from_date: "2024-09-11", to_date: "2024-09-15", interval: "15")
+      def intraday(from_date:, to_date:, interval:, **options)
+        params = build_historical_data_params(from_date: from_date, to_date: to_date, interval: interval, **options)
+        DhanHQ::Models::HistoricalData.intraday(params)
+      end
+
+      ##
+      # Fetches the expiry list for this instrument (option chain).
+      #
+      # @return [Array<String>] List of expiry dates in YYYY-MM-DD format
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("NSE_FNO", "NIFTY")
+      #   expiries = instrument.expiry_list
+      def expiry_list
+        params = {
+          underlying_scrip: security_id.to_i,
+          underlying_seg: exchange_segment
+        }
+        DhanHQ::Models::OptionChain.fetch_expiry_list(params)
+      end
+
+      ##
+      # Fetches the option chain for this instrument.
+      #
+      # @param expiry [String] Expiry date in YYYY-MM-DD format
+      # @return [Hash] Option chain data
+      # @example
+      #   instrument = DhanHQ::Models::Instrument.find("NSE_FNO", "NIFTY")
+      #   chain = instrument.option_chain(expiry: "2024-02-29")
+      def option_chain(expiry:)
+        params = {
+          underlying_scrip: security_id.to_i,
+          underlying_seg: exchange_segment,
+          expiry: expiry
+        }
+        DhanHQ::Models::OptionChain.fetch(params)
+      end
+
+      private
+
+      ##
+      # Builds market feed params from instrument attributes.
+      #
+      # @return [Hash] Market feed params in format { "EXCHANGE_SEGMENT": [security_id] }
+      def build_market_feed_params
+        { exchange_segment => [security_id.to_i] }
+      end
+
+      ##
+      # Builds historical data params from instrument attributes.
+      #
+      # @param from_date [String] Start date
+      # @param to_date [String] End date
+      # @param interval [String, nil] Time interval for intraday
+      # @param options [Hash] Additional options
+      # @return [Hash] Historical data params
+      def build_historical_data_params(from_date:, to_date:, interval: nil, **options)
+        params = {
+          security_id: security_id,
+          exchange_segment: exchange_segment,
+          instrument: instrument,
+          from_date: from_date,
+          to_date: to_date
+        }
+
+        params[:interval] = interval if interval
+        params.merge!(options) if options.any?
+
+        params
+      end
+    end
+  end
+end