DhanHQ 2.1.5 → 2.1.6

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

@@ -6,28 +6,40 @@ require_relative "connection"
 module DhanHQ
   module WS
     module Orders
-      # WebSocket client for real-time order updates
+      ##
+      # 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?
 
@@ -37,17 +49,166 @@ module DhanHQ
           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]
@@ -55,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,107 +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
+      ##
       # WebSocket connection for real-time order updates
-      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
+      # 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|
-              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}")
+              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
 
@@ -114,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 },
@@ -132,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,11 +4,39 @@ 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
+      ##
+      # 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
 end

data/lib/DhanHQ/ws/segments.rb

@@ -50,9 +50,16 @@ module DhanHQ
       # @param hash [Hash]
       # @return [Hash] Normalized instrument hash.
       def self.normalize_instrument(hash)
-        seg = to_request_string(hash[:ExchangeSegment] || hash["ExchangeSegment"])
+        raw_segment = hash[:ExchangeSegment] || hash["ExchangeSegment"]
         sid = (hash[:SecurityId] || hash["SecurityId"]).to_s
-        { ExchangeSegment: seg, SecurityId: sid }
+        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.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/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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 2.1.5
+  version: 2.1.6
 platform: ruby
 authors:
 - Shubham Taywade
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: dry-validation
   requirement: !ruby/object:Gem::Requirement
@@ -162,14 +176,26 @@ files:
 - config/initializers/order_update_hub.rb
 - diagram.html
 - diagram.md
+- docs/live_order_updates.md
 - docs/rails_integration.md
+- docs/rails_websocket_integration.md
+- docs/standalone_ruby_websocket_integration.md
 - docs/technical_analysis.md
+- docs/websocket_integration.md
+- examples/comprehensive_websocket_examples.rb
+- examples/instrument_finder_test.rb
+- examples/live_order_updates.rb
+- examples/market_depth_example.rb
+- examples/market_feed_example.rb
+- examples/order_update_example.rb
+- examples/trading_fields_example.rb
 - exe/DhanHQ
 - lib/DhanHQ/client.rb
 - lib/DhanHQ/config.rb
 - lib/DhanHQ/configuration.rb
 - lib/DhanHQ/constants.rb
 - lib/DhanHQ/contracts/base_contract.rb
+- lib/DhanHQ/contracts/expired_options_data_contract.rb
 - lib/DhanHQ/contracts/historical_data_contract.rb
 - lib/DhanHQ/contracts/instrument_list_contract.rb
 - lib/DhanHQ/contracts/margin_calculator_contract.rb
@@ -180,6 +206,7 @@ files:
 - lib/DhanHQ/contracts/place_order_contract.rb
 - lib/DhanHQ/contracts/position_conversion_contract.rb
 - lib/DhanHQ/contracts/slice_order_contract.rb
+- lib/DhanHQ/contracts/trade_contract.rb
 - lib/DhanHQ/core/base_api.rb
 - lib/DhanHQ/core/base_model.rb
 - lib/DhanHQ/core/base_resource.rb
@@ -194,6 +221,7 @@ files:
 - lib/DhanHQ/helpers/validation_helper.rb
 - lib/DhanHQ/json_loader.rb
 - lib/DhanHQ/models/edis.rb
+- lib/DhanHQ/models/expired_options_data.rb
 - lib/DhanHQ/models/forever_order.rb
 - lib/DhanHQ/models/funds.rb
 - lib/DhanHQ/models/historical_data.rb
@@ -205,6 +233,7 @@ files:
 - lib/DhanHQ/models/market_feed.rb
 - lib/DhanHQ/models/option_chain.rb
 - lib/DhanHQ/models/order.rb
+- lib/DhanHQ/models/order_update.rb
 - lib/DhanHQ/models/position.rb
 - lib/DhanHQ/models/profile.rb
 - lib/DhanHQ/models/super_order.rb
@@ -214,6 +243,7 @@ files:
 - lib/DhanHQ/requests/optionchain/nifty_expiries.json
 - lib/DhanHQ/requests/orders/create.json
 - lib/DhanHQ/resources/edis.rb
+- lib/DhanHQ/resources/expired_options_data.rb
 - lib/DhanHQ/resources/forever_orders.rb
 - lib/DhanHQ/resources/funds.rb
 - lib/DhanHQ/resources/historical_data.rb
@@ -231,10 +261,14 @@ files:
 - lib/DhanHQ/resources/trades.rb
 - lib/DhanHQ/version.rb
 - lib/DhanHQ/ws.rb
+- lib/DhanHQ/ws/base_connection.rb
 - lib/DhanHQ/ws/client.rb
 - lib/DhanHQ/ws/cmd_bus.rb
 - lib/DhanHQ/ws/connection.rb
 - lib/DhanHQ/ws/decoder.rb
+- lib/DhanHQ/ws/market_depth.rb
+- lib/DhanHQ/ws/market_depth/client.rb
+- lib/DhanHQ/ws/market_depth/decoder.rb
 - lib/DhanHQ/ws/orders.rb
 - lib/DhanHQ/ws/orders/client.rb
 - lib/DhanHQ/ws/orders/connection.rb