DhanHQ 2.1.3 → 2.1.6

data/lib/DhanHQ/ws/orders/client.rb

@@ -6,45 +6,209 @@ require_relative "connection"
 module DhanHQ
   module WS
     module Orders
+      ##
+      # Enhanced WebSocket client for real-time order updates
+      # Provides comprehensive order state tracking and event handling
+      # rubocop:disable Metrics/ClassLength
       class Client
-        def initialize(url: nil)
+        def initialize(url: nil, **options)
           @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
-          @started   = Concurrent::AtomicBoolean.new(false)
-          cfg        = DhanHQ.configuration
-          @url       = url || cfg.ws_order_url
+          @started = Concurrent::AtomicBoolean.new(false)
+          @order_tracker = Concurrent::Map.new
+          cfg = DhanHQ.configuration
+          @url = url || cfg.ws_order_url
+          @connection_options = options
         end
 
+        ##
+        # Start the WebSocket connection and begin receiving order updates
+        # @return [Client] self for method chaining
         def start
           return self if @started.true?
+
           @started.make_true
-          @conn = Connection.new(url: @url) do |msg|
-            emit(:update, msg) if msg&.dig(:Type) == "order_alert"
-            emit(:raw, msg)
-          end
+          @conn = Connection.new(url: @url, **@connection_options)
+          @conn.on(:open) { emit(:open, true) }
+          @conn.on(:close) { |payload| emit(:close, payload) }
+          @conn.on(:error) { |error| emit(:error, error) }
+          @conn.on(:message) { |msg| handle_message(msg) }
           @conn.start
           DhanHQ::WS::Registry.register(self) if defined?(DhanHQ::WS::Registry)
           self
         end
 
+        ##
+        # Stop the WebSocket connection
+        # @return [void]
         def stop
           return unless @started.true?
+
           @started.make_false
           @conn&.stop
           emit(:close, true)
           DhanHQ::WS::Registry.unregister(self) if defined?(DhanHQ::WS::Registry)
         end
 
+        ##
+        # Force disconnect the WebSocket
+        # @return [void]
         def disconnect!
           @conn&.disconnect!
         end
 
-        def on(event, &blk)
-          @callbacks[event] << blk
+        ##
+        # Register event handlers
+        # @param event [Symbol] Event type (:update, :raw, :status_change, :execution, :error)
+        # @param block [Proc] Event handler
+        # @return [Client] self for method chaining
+        def on(event, &block)
+          @callbacks[event] << block
           self
         end
 
+        ##
+        # Get current order state for a specific order
+        # @param order_no [String] Order number
+        # @return [OrderUpdate, nil] Latest order update or nil if not found
+        def order_state(order_no)
+          @order_tracker[order_no]
+        end
+
+        ##
+        # Get all tracked orders
+        # @return [Hash] Hash of order_no => OrderUpdate
+        def all_orders
+          @order_tracker.dup
+        end
+
+        ##
+        # Get orders by status
+        # @param status [String] Order status (TRANSIT, PENDING, REJECTED, etc.)
+        # @return [Array<OrderUpdate>] Orders with the specified status
+        def orders_by_status(status)
+          @order_tracker.values.select { |order| order.status == status }
+        end
+
+        ##
+        # Get orders by symbol
+        # @param symbol [String] Trading symbol
+        # @return [Array<OrderUpdate>] Orders for the specified symbol
+        def orders_by_symbol(symbol)
+          @order_tracker.values.select { |order| order.symbol == symbol }
+        end
+
+        ##
+        # Get partially executed orders
+        # @return [Array<OrderUpdate>] Orders that are partially executed
+        def partially_executed_orders
+          @order_tracker.values.select(&:partially_executed?)
+        end
+
+        ##
+        # Get fully executed orders
+        # @return [Array<OrderUpdate>] Orders that are fully executed
+        def fully_executed_orders
+          @order_tracker.values.select(&:fully_executed?)
+        end
+
+        ##
+        # Get pending orders (not executed)
+        # @return [Array<OrderUpdate>] Orders that are not executed
+        def pending_orders
+          @order_tracker.values.select(&:not_executed?)
+        end
+
+        ##
+        # Check if connection is active
+        # @return [Boolean] true if connected
+        def connected?
+          @conn&.open? || false
+        end
+
         private
 
+        ##
+        # Handle incoming WebSocket messages
+        # @param msg [Hash] Raw WebSocket message
+        def handle_message(msg)
+          # Emit raw message for debugging
+          emit(:raw, msg)
+
+          # Handle order updates
+          if msg&.dig(:Type) == "order_alert"
+            order_update = DhanHQ::Models::OrderUpdate.from_websocket_message(msg)
+            handle_order_update(order_update) if order_update
+          end
+
+          # Handle other message types
+          emit(:message, msg)
+        end
+
+        ##
+        # Handle order update and track state changes
+        # @param order_update [OrderUpdate] Parsed order update
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def handle_order_update(order_update)
+          order_no = order_update.order_no
+          previous_state = @order_tracker[order_no]
+
+          # Update order tracker
+          @order_tracker[order_no] = order_update
+
+          # Emit update event
+          emit(:update, order_update)
+
+          # Check for status changes
+          if previous_state && previous_state.status != order_update.status
+            emit(:status_change, {
+                   order_update: order_update,
+                   previous_status: previous_state.status,
+                   new_status: order_update.status
+                 })
+          end
+
+          # Check for execution updates
+          if previous_state && previous_state.traded_qty != order_update.traded_qty
+            emit(:execution, {
+                   order_update: order_update,
+                   previous_traded_qty: previous_state.traded_qty,
+                   new_traded_qty: order_update.traded_qty,
+                   execution_percentage: order_update.execution_percentage
+                 })
+          end
+
+          # Emit specific status events
+          emit_status_specific_events(order_update, previous_state)
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+        ##
+        # Emit status-specific events
+        # @param order_update [OrderUpdate] Current order update
+        # @param previous_state [OrderUpdate, nil] Previous order state
+        # rubocop:disable Metrics/MethodLength
+        def emit_status_specific_events(order_update, _previous_state)
+          case order_update.status
+          when "TRANSIT"
+            emit(:order_transit, order_update)
+          when "PENDING"
+            emit(:order_pending, order_update)
+          when "REJECTED"
+            emit(:order_rejected, order_update)
+          when "CANCELLED"
+            emit(:order_cancelled, order_update)
+          when "TRADED"
+            emit(:order_traded, order_update)
+          when "EXPIRED"
+            emit(:order_expired, order_update)
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        ##
+        # Emit events to registered callbacks
+        # @param event [Symbol] Event type
+        # @param payload [Object] Event payload
         def emit(event, payload)
           list = begin
             @callbacks[event]
@@ -52,8 +216,11 @@ module DhanHQ
             []
           end
           list.each { |cb| cb.call(payload) }
+        rescue StandardError => e
+          DhanHQ.logger&.error("[DhanHQ::WS::Orders] Error in event handler: #{e.class} #{e.message}")
         end
       end
+      # rubocop:enable Metrics/ClassLength
     end
   end
 end

data/lib/DhanHQ/ws/orders/connection.rb

@@ -1,108 +1,52 @@
 # frozen_string_literal: true
 
-require "eventmachine"
-require "faye/websocket"
-require "json"
-require "thread" # rubocop:disable Lint/RedundantRequireStatement
+require_relative "../base_connection"
 
 module DhanHQ
   module WS
     module Orders
-      class Connection
-        COOL_OFF_429 = 60
-        MAX_BACKOFF  = 90
-
-        def initialize(url:, &on_json)
-          @url           = url
-          @on_json       = on_json
-          @ws            = nil
-          @stop          = false
-          @cooloff_until = nil
-        end
-
-        def start
-          Thread.new { loop_run }
-          self
-        end
-
-        def stop
-          @stop = true
-          @ws&.close
-        end
-
-        def disconnect!
-          # spec does not list a separate disconnect message; just close
-          @ws&.close
+      ##
+      # WebSocket connection for real-time order updates
+      # Inherits from BaseConnection for consistent behavior
+      class Connection < BaseConnection
+        ##
+        # Initialize Orders WebSocket connection
+        # @param url [String] WebSocket endpoint URL
+        # @param options [Hash] Connection options
+        def initialize(url:, **options)
+          super
         end
 
         private
 
-        def loop_run
-          backoff = 2.0
-          until @stop
-            failed  = false
-            got_429 = false
-            sleep (@cooloff_until - Time.now).ceil if @cooloff_until && Time.now < @cooloff_until
-
-            begin
-              failed, got_429 = run_session
-            rescue StandardError => e
-              DhanHQ.logger&.error("[DhanHQ::WS::Orders] crashed #{e.class} #{e.message}")
-              failed = true
-            ensure
-              break if @stop
-
-              if got_429
-                @cooloff_until = Time.now + COOL_OFF_429
-                DhanHQ.logger&.warn("[DhanHQ::WS::Orders] cooling off #{COOL_OFF_429}s due to 429")
-              end
-
-              if failed
-                sleep_time = [backoff, MAX_BACKOFF].min
-                jitter = rand(0.2 * sleep_time)
-                DhanHQ.logger&.warn("[DhanHQ::WS::Orders] reconnecting in #{(sleep_time + jitter).round(1)}s")
-                sleep(sleep_time + jitter)
-                backoff *= 2.0
-              else
-                backoff = 2.0
-              end
-            end
-          end
-        end
-
+        ##
+        # Run WebSocket session for Orders
+        # @return [Array<Boolean>] [failed, got_429]
         def run_session
-          failed  = false
+          failed = false
           got_429 = false
-          latch   = Queue.new
+          latch = Queue.new
 
           runner = proc do |stopper|
             @ws = Faye::WebSocket::Client.new(@url, nil, headers: default_headers)
 
             @ws.on :open do |_|
-              DhanHQ.logger&.info("[DhanHQ::WS::Orders] open")
-              send_login
+              handle_open
+              authenticate
             end
 
             @ws.on :message do |ev|
-              begin
-                msg = JSON.parse(ev.data, symbolize_names: true)
-                @on_json&.call(msg)
-              rescue StandardError => e
-                DhanHQ.logger&.error("[DhanHQ::WS::Orders] bad JSON #{e.class}: #{e.message}")
-              end
+              handle_message(ev)
             end
 
             @ws.on :close do |ev|
-              DhanHQ.logger&.warn("[DhanHQ::WS::Orders] close #{ev.code} #{ev.reason}")
-              failed  = (ev.code != 1000)
-              got_429 = ev.reason.to_s.include?("429")
+              failed, got_429 = handle_close(ev)
               latch << true
               stopper.call
             end
 
             @ws.on :error do |ev|
-              DhanHQ.logger&.error("[DhanHQ::WS::Orders] error #{ev.message}")
-              failed = true
+              failed, got_429 = handle_error(ev)
             end
           end
 
@@ -115,16 +59,29 @@ module DhanHQ
           end
 
           latch.pop
-
           [failed, got_429]
         end
 
-        def default_headers
-          { "User-Agent" => "dhanhq-ruby/#{defined?(DhanHQ::VERSION) ? DhanHQ::VERSION : "dev"} Ruby/#{RUBY_VERSION}" }
+        ##
+        # Process incoming WebSocket message
+        # @param ev [Event] WebSocket message event
+        def handle_message(ev)
+          msg = JSON.parse(ev.data, symbolize_names: true)
+          emit(:raw, msg)
+          emit(:message, msg)
+        rescue JSON::ParserError => e
+          DhanHQ.logger&.error("[DhanHQ::WS::Orders] Bad JSON #{e.class}: #{e.message}")
+          emit(:error, e)
+        rescue StandardError => e
+          DhanHQ.logger&.error("[DhanHQ::WS::Orders] Message processing error: #{e.class} #{e.message}")
+          emit(:error, e)
         end
 
-        def send_login
+        ##
+        # Authenticate with DhanHQ Orders WebSocket
+        def authenticate
           cfg = DhanHQ.configuration
+
           if cfg.ws_user_type.to_s.upcase == "PARTNER"
             payload = {
               LoginReq: { MsgCode: 42, ClientId: cfg.partner_id },
@@ -133,14 +90,15 @@ module DhanHQ
             }
           else
             token = cfg.access_token or raise "DhanHQ.access_token not set"
-            cid   = cfg.client_id    or raise "DhanHQ.client_id not set"
+            cid = cfg.client_id or raise "DhanHQ.client_id not set"
             payload = {
               LoginReq: { MsgCode: 42, ClientId: cid, Token: token },
               UserType: "SELF"
             }
           end
+
           DhanHQ.logger&.info("[DhanHQ::WS::Orders] LOGIN -> (#{payload[:UserType]})")
-          @ws.send(payload.to_json)
+          send_message(payload)
         end
       end
     end

data/lib/DhanHQ/ws/orders.rb

@@ -4,9 +4,38 @@ require_relative "orders/client"
 
 module DhanHQ
   module WS
+    ##
+    # WebSocket orders module for real-time order updates
+    # Provides comprehensive order state tracking and event handling
     module Orders
-      def self.connect(&on_update)
-        Client.new.start.on(:update, &on_update)
+      ##
+      # Connect to order updates WebSocket with a simple callback
+      # @param block [Proc] Callback for order updates
+      # @return [Client] WebSocket client instance
+      def self.connect(&)
+        Client.new.start.on(:update, &)
+      end
+
+      ##
+      # Create a new order updates client with advanced features
+      # @param url [String, nil] Optional custom WebSocket URL
+      # @return [Client] New client instance
+      def self.client(url: nil)
+        Client.new(url: url)
+      end
+
+      ##
+      # Quick connection with multiple event handlers
+      # @param handlers [Hash] Event handlers
+      # @return [Client] Started client instance
+      def self.connect_with_handlers(handlers = {})
+        client = Client.new.start
+
+        handlers.each do |event, handler|
+          client.on(event, &handler)
+        end
+
+        client
       end
     end
   end

data/lib/DhanHQ/ws/registry.rb

@@ -3,6 +3,7 @@
 require "concurrent"
 
 module DhanHQ
+  # WebSocket registry for managing connections and subscriptions
   module WS
     # Tracks the set of active WebSocket clients so they can be collectively
     # disconnected when required.

data/lib/DhanHQ/ws/segments.rb

@@ -47,12 +47,19 @@ module DhanHQ
       #   - ExchangeSegment is a STRING enum (e.g., "NSE_FNO")
       #   - SecurityId is a STRING
       #
-      # @param h [Hash]
+      # @param hash [Hash]
       # @return [Hash] Normalized instrument hash.
-      def self.normalize_instrument(h)
-        seg = to_request_string(h[:ExchangeSegment] || h["ExchangeSegment"])
-        sid = (h[:SecurityId] || h["SecurityId"]).to_s
-        { ExchangeSegment: seg, SecurityId: sid }
+      def self.normalize_instrument(hash)
+        raw_segment = hash[:ExchangeSegment] || hash["ExchangeSegment"]
+        sid = (hash[:SecurityId] || hash["SecurityId"]).to_s
+        seg = to_request_string(raw_segment)
+        # Some instruments—especially indices—require IDX_I even when the caller
+        # supplies only the security token. Fall back to documented defaults.
+        if seg.nil? || seg.empty?
+          fallback = default_segment_for_security_id(sid)
+          seg = fallback unless fallback.nil?
+        end
+        { ExchangeSegment: seg.to_s, SecurityId: sid }
       end
 
       # Normalizes all instruments in the provided list.
@@ -70,6 +77,15 @@ module DhanHQ
       def self.from_code(code_byte)
         CODE_TO_STRING[code_byte] || code_byte.to_s
       end
+
+      # Known security ids that must be subscribed on the index segment.
+      INDEX_SECURITY_IDS = %w[13 25 51].freeze
+
+      def self.default_segment_for_security_id(security_id)
+        return "IDX_I" if INDEX_SECURITY_IDS.include?(security_id.to_s)
+
+        nil
+      end
     end
   end
 end

data/lib/DhanHQ/ws/sub_state.rb

@@ -53,7 +53,7 @@ module DhanHQ
 
       private
 
-      def key_for(i) = "#{i[:ExchangeSegment]}:#{i[:SecurityId]}"
+      def key_for(instrument) = "#{instrument[:ExchangeSegment]}:#{instrument[:SecurityId]}"
     end
   end
 end

data/lib/DhanHQ/ws.rb

@@ -2,12 +2,13 @@
 
 require_relative "ws/client"
 require_relative "ws/orders"
+require_relative "ws/market_depth"
 
 module DhanHQ
   # Namespace for the WebSocket streaming client helpers.
   #
-  # The helpers provide a simple façade around {DhanHQ::WS::Client} so that
-  # applications can start streaming market data with a single method call.
+  # The helpers provide a simple façade around WebSocket clients so that
+  # applications can start streaming data with single method calls.
   module WS
     # Establishes a WebSocket connection and yields decoded ticks.
     #

data/lib/{DhanHQ.rb → dhan_hq.rb}

@@ -30,6 +30,8 @@ require_relative "DhanHQ/contracts/historical_data_contract"
 require_relative "DhanHQ/contracts/margin_calculator_contract"
 require_relative "DhanHQ/contracts/position_conversion_contract"
 require_relative "DhanHQ/contracts/slice_order_contract"
+require_relative "DhanHQ/contracts/trade_contract"
+require_relative "DhanHQ/contracts/expired_options_data_contract"
 
 # Resources
 require_relative "DhanHQ/resources/option_chain"
@@ -48,6 +50,7 @@ require_relative "DhanHQ/resources/instruments"
 require_relative "DhanHQ/resources/edis"
 require_relative "DhanHQ/resources/kill_switch"
 require_relative "DhanHQ/resources/profile"
+require_relative "DhanHQ/resources/expired_options_data"
 
 # Models
 require_relative "DhanHQ/models/order"
@@ -66,6 +69,8 @@ require_relative "DhanHQ/models/margin"
 require_relative "DhanHQ/models/edis"
 require_relative "DhanHQ/models/kill_switch"
 require_relative "DhanHQ/models/profile"
+require_relative "DhanHQ/models/order_update"
+require_relative "DhanHQ/models/expired_options_data"
 
 require_relative "DhanHQ/constants"
 require_relative "DhanHQ/ws"

data/lib/dhanhq/analysis/helpers/bias_aggregator.rb

@@ -2,6 +2,7 @@
 
 module DhanHQ
   module Analysis
+    # Aggregates indicator scores across timeframes into a single bias and confidence score
     class BiasAggregator
       DEFAULT_WEIGHTS = { m1: 0.1, m5: 0.2, m15: 0.25, m25: 0.15, m60: 0.3 }.freeze
 
@@ -44,36 +45,35 @@ module DhanHQ
       private
 
       def score_tf(val)
-        rsi = val[:rsi]
+        rsi  = val[:rsi]
         macd = val[:macd] || {}
         hist = macd[:hist]
-        adx = val[:adx]
+        adx  = val[:adx]
 
-        rsi_component = case rsi
-                        when nil then 0.5
+        rsi_component = if rsi.nil?
+                          0.5
+                        elsif rsi >= 55
+                          0.65
+                        elsif rsi <= 45
+                          0.35
                         else
-                          return 0.65 if rsi >= 55
-                          return 0.35 if rsi <= 45
-
                           0.5
                         end
 
-        macd_component = case hist
-                         when nil then 0.5
+        macd_component = if hist.nil?
+                           0.5
                          else
                            hist >= 0 ? 0.6 : 0.4
                          end
 
-        adx_component = case adx
-                        when nil then 0.5
+        adx_component = if adx.nil?
+                          0.5
+                        elsif adx >= @strong_adx
+                          0.65
+                        elsif adx >= @min_adx
+                          0.55
                         else
-                          if adx >= @strong_adx
-                            0.65
-                          elsif adx >= @min_adx
-                            0.55
-                          else
-                            0.45
-                          end
+                          0.45
                         end
 
         (rsi_component * 0.4) + (macd_component * 0.3) + (adx_component * 0.3)

data/lib/dhanhq/analysis/helpers/moneyness_helper.rb

@@ -2,6 +2,7 @@
 
 module DhanHQ
   module Analysis
+    # Helper module to determine the recommended moneyness (ITM/ATM/OTM) based on market conditions
     module MoneynessHelper
       module_function
 

data/lib/dhanhq/analysis/multi_timeframe_analyzer.rb

@@ -5,7 +5,9 @@ require "dry/validation"
 
 module DhanHQ
   module Analysis
+    # Analyzes multi-timeframe indicator data to produce a consolidated bias summary
     class MultiTimeframeAnalyzer
+      # Input validation contract for multi-timeframe analyzer
       class InputContract < Dry::Validation::Contract
         params do
           required(:meta).filled(:hash)

data/lib/dhanhq/analysis/options_buying_advisor.rb

@@ -6,6 +6,7 @@ require_relative "../contracts/options_buying_advisor_contract"
 
 module DhanHQ
   module Analysis
+    # Options buying advisor for INDEX options (NIFTY/BANKNIFTY/SENSEX)
     class OptionsBuyingAdvisor
       DEFAULT_CONFIG = {
         timeframe_weights: { m1: 0.1, m5: 0.2, m15: 0.25, m25: 0.15, m60: 0.3 },
@@ -229,10 +230,10 @@ module DhanHQ
         { decision: :no_trade, reason: reason }
       end
 
-      def deep_merge(a, b)
-        return a unless b
+      def deep_merge(first_hash, second_hash)
+        return first_hash unless second_hash
 
-        a.merge(b) { |_, av, bv| av.is_a?(Hash) && bv.is_a?(Hash) ? deep_merge(av, bv) : bv }
+        first_hash.merge(second_hash) { |_, av, bv| av.is_a?(Hash) && bv.is_a?(Hash) ? deep_merge(av, bv) : bv }
       end
 
       def deep_symbolize(obj)

data/lib/dhanhq/contracts/options_buying_advisor_contract.rb

@@ -4,6 +4,7 @@ require "dry/validation"
 
 module DhanHQ
   module Contracts
+    # Validation contract for options buying advisor input
     class OptionsBuyingAdvisorContract < Dry::Validation::Contract
       params do
         required(:meta).hash do

data/lib/ta/candles.rb

@@ -3,6 +3,7 @@
 require "time"
 
 module TA
+  # Candle data processing and resampling utilities
   module Candles
     module_function