DhanHQ 2.1.0

data/lib/DhanHQ/resources/super_orders.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for multi-leg super orders.
+    class SuperOrders < BaseAPI
+      # Super orders are executed via the trading API.
+      API_TYPE = :order_api
+      # Base path for super order endpoints.
+      HTTP_PATH = "/v2/super/orders"
+
+      # Lists all configured super orders.
+      #
+      # @return [Array<Hash>]
+      def all
+        get("")
+      end
+
+      # Creates a new super order.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def create(params)
+        post("", params: params)
+      end
+
+      # Updates an existing super order.
+      #
+      # @param order_id [String]
+      # @param params [Hash]
+      # @return [Hash]
+      def update(order_id, params)
+        put("/#{order_id}", params: params)
+      end
+
+      # Cancels a specific leg from a super order.
+      #
+      # @param order_id [String]
+      # @param leg_name [String]
+      # @return [Hash]
+      def cancel(order_id, leg_name)
+        delete("/#{order_id}/#{leg_name}")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/trades.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Provides access to current day trades endpoints
+    class Trades < BaseAPI
+      # Trade history is fetched from the trading API tier.
+      API_TYPE = :order_api
+      # Base path for trade retrieval.
+      HTTP_PATH = "/v2/trades"
+
+      # GET /v2/trades
+      def all
+        get("")
+      end
+
+      # GET /v2/trades/{order-id}
+      def find(order_id)
+        get("/#{order_id}")
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Semantic version of the DhanHQ client gem.
+  VERSION = "2.1.0"
+end

data/lib/DhanHQ/ws/client.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require_relative "cmd_bus"
+require_relative "sub_state"
+require_relative "connection"
+require_relative "decoder"
+require_relative "segments"
+require_relative "registry"
+
+module DhanHQ
+  module WS
+    # Client responsible for managing the lifecycle of a streaming connection
+    # to the DhanHQ market data WebSocket.
+    #
+    # The client encapsulates reconnection logic, subscription state tracking,
+    # and event dispatching. It is typically used indirectly via
+    # {DhanHQ::WS.connect}, but can also be instantiated directly for more
+    # advanced flows.
+    class Client
+      # @param mode [Symbol] Feed mode (:ticker, :quote, :full).
+      # @param url [String, nil] Optional custom WebSocket endpoint.
+      def initialize(mode: :ticker, url: nil)
+        @mode  = mode # :ticker, :quote, :full (adjust to your API)
+        @bus   = CmdBus.new
+        @state = SubState.new
+        @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
+        @started = Concurrent::AtomicBoolean.new(false)
+
+        token = DhanHQ.configuration.access_token or raise "DhanHQ.access_token not set"
+        cid   = DhanHQ.configuration.client_id or raise "DhanHQ.client_id not set"
+        ver   = (DhanHQ.configuration.respond_to?(:ws_version) && DhanHQ.configuration.ws_version) || 2
+        @url  = url || "wss://api-feed.dhan.co?version=#{ver}&token=#{token}&clientId=#{cid}&authType=2"
+      end
+
+      # Starts the WebSocket connection and event loop.
+      #
+      # @return [DhanHQ::WS::Client] self, to allow method chaining.
+      def start
+        return self if @started.true?
+
+        @started.make_true
+        @conn = Connection.new(url: @url, mode: @mode, bus: @bus, state: @state) do |binary|
+          tick = Decoder.decode(binary)
+          emit(:tick, tick) if tick
+        end
+        Registry.register(self)
+        install_at_exit_once!
+        @conn.start
+        self
+      end
+
+      # Gracefully stops the connection without sending a manual disconnect
+      # frame.
+      #
+      # @return [DhanHQ::WS::Client] self.
+      def stop
+        return unless @started.true?
+
+        @started.make_false
+        @conn&.stop
+        Registry.unregister(self)
+        emit(:close, true)
+        self
+      end
+
+      # Immediately disconnects from the feed by sending the disconnect frame
+      # (RequestCode 12) before closing the socket.
+      #
+      # @return [DhanHQ::WS::Client] self.
+      def disconnect!
+        return self unless @started.true?
+
+        @started.make_false
+        @conn&.disconnect!
+        Registry.unregister(self)
+        emit(:close, true)
+        self
+      end
+
+      # Indicates whether the underlying WebSocket connection is open.
+      #
+      # @return [Boolean]
+      def connected?
+        return false unless @started.true?
+
+        @conn&.open? || false
+      end
+
+      # Subscribes to updates for a single instrument.
+      #
+      # @param segment [String, Symbol, Integer]
+      # @param security_id [String, Integer]
+      # @return [DhanHQ::WS::Client] self.
+      def subscribe_one(segment:, security_id:)
+        norm = Segments.normalize_instrument(ExchangeSegment: segment, SecurityId: security_id)
+        DhanHQ.logger&.info("[DhanHQ::WS] subscribe_one (normalized) -> #{norm}")
+        @bus.sub([prune(norm)])
+        self
+      end
+
+      # Subscribes to updates for a list of instruments.
+      #
+      # @param list [Array<Hash>] Array containing instrument hashes with
+      #   +:ExchangeSegment+ and +:SecurityId+ keys.
+      # @return [DhanHQ::WS::Client] self.
+      def subscribe_many(list)
+        norms = Segments.normalize_instruments(list).map { |i| prune(i) }
+        DhanHQ.logger&.info("[DhanHQ::WS] subscribe_many (normalized) -> #{norms}")
+        @bus.sub(norms)
+        self
+      end
+
+      # Removes the subscription for a single instrument.
+      #
+      # @param segment [String, Symbol, Integer]
+      # @param security_id [String, Integer]
+      # @return [DhanHQ::WS::Client] self.
+      def unsubscribe_one(segment:, security_id:)
+        norm = Segments.normalize_instrument(ExchangeSegment: segment, SecurityId: security_id)
+        DhanHQ.logger&.info("[DhanHQ::WS] unsubscribe_one (normalized) -> #{norm}")
+        @bus.unsub([prune(norm)])
+        self
+      end
+
+      # Removes the subscriptions for a list of instruments.
+      #
+      # @param list [Array<Hash>] Instrument definitions to unsubscribe.
+      # @return [DhanHQ::WS::Client] self.
+      def unsubscribe_many(list)
+        norms = Segments.normalize_instruments(list).map { |i| prune(i) }
+        DhanHQ.logger&.info("[DhanHQ::WS] unsubscribe_many (normalized) -> #{norms}")
+        @bus.unsub(norms)
+        self
+      end
+
+      # Installs a single +at_exit+ hook to close open WebSocket clients.
+      #
+      # @return [void]
+      def self.install_at_exit_hook!
+        return if defined?(@_at_exit_installed) && @_at_exit_installed
+
+        @_at_exit_installed = true
+        at_exit do
+          DhanHQ.logger&.info("[DhanHQ::WS] at_exit: disconnecting all local clients")
+          Registry.stop_all
+        rescue StandardError => e
+          DhanHQ.logger&.debug("[DhanHQ::WS] at_exit error #{e.class}: #{e.message}")
+        end
+      end
+
+      # Registers a callback for a given event.
+      #
+      # @param event [Symbol] Event name (:tick, :open, :close, :error).
+      # @yieldparam payload [Object] Event payload.
+      # @return [DhanHQ::WS::Client] self.
+      def on(event, &blk)
+        @callbacks[event] << blk
+        self
+      end
+
+      private
+
+      def prune(h) = { ExchangeSegment: h[:ExchangeSegment], SecurityId: h[:SecurityId] }
+
+      def emit(event, payload)
+        begin
+          @callbacks[event].dup
+        rescue StandardError
+          []
+        end.each { |cb| cb.call(payload) }
+      end
+
+      def install_at_exit_once!
+        return if defined?(@at_exit_installed) && @at_exit_installed
+
+        @at_exit_installed = true
+        at_exit { Registry.stop_all }
+      end
+    end
+  end
+end

data/lib/DhanHQ/ws/cmd_bus.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module WS
+    # Thread-safe queue that buffers subscription commands until the
+    # connection is ready to send them.
+    class CmdBus
+      # Represents a subscription command queued for execution.
+      Command = Struct.new(:op, :payload, keyword_init: true)
+
+      def initialize
+        @q = Queue.new
+      end
+
+      # Queues a subscribe command.
+      #
+      # @param list [Array<Hash>] Instruments to subscribe.
+      # @return [Command]
+      def sub(list) = @q.push(Command.new(op: :sub, payload: list))
+
+      # Queues an unsubscribe command.
+      #
+      # @param list [Array<Hash>] Instruments to unsubscribe.
+      # @return [Command]
+      def unsub(list) = @q.push(Command.new(op: :unsub, payload: list))
+
+      # Drains all queued commands without blocking.
+      #
+      # @return [Array<Command>]
+      def drain
+        out = []
+        loop { out << @q.pop(true) }
+      rescue ThreadError
+        out
+      end
+    end
+  end
+end

data/lib/DhanHQ/ws/connection.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "eventmachine"
+require "faye/websocket"
+require "json"
+
+module DhanHQ
+  module WS
+    # Low-level wrapper responsible for establishing and maintaining the raw
+    # WebSocket connection to the streaming API.
+    class Connection
+      SUB_CODES   = { ticker: 15, quote: 17, full: 21 }.freeze # adjust if needed
+      # Request codes used when unsubscribing from feeds.
+      UNSUB_CODES = { ticker: 16, quote: 18, full: 22 }.freeze
+
+      COOL_OFF_429 = 60  # seconds to cool off on 429
+      MAX_BACKOFF  = 90  # cap exponential backoff
+
+      attr_reader :stopping
+
+      # @param url [String] WebSocket endpoint URL.
+      # @param mode [Symbol] Feed mode (:ticker, :quote, :full).
+      # @param bus [DhanHQ::WS::CmdBus] Command queue feeding subscription
+      #   changes.
+      # @param state [DhanHQ::WS::SubState] Tracks subscription status.
+      # @yield [binary]
+      # @yieldparam binary [String] Raw binary frame received from the socket.
+      def initialize(url:, mode:, bus:, state:, &on_binary)
+        @url = url
+        @mode = mode
+        @bus = bus
+        @state = state
+        @on_binary = on_binary
+        @stop = false
+        @stopping = false
+        @ws     = nil
+        @timer  = nil
+        @cooloff_until = nil
+        @thr = nil
+      end
+
+      # Starts the connection in a background thread.
+      #
+      # @return [DhanHQ::WS::Connection] self.
+      def start
+        return self if @thr&.alive?
+
+        @thr = Thread.new { loop_run }
+        self
+      end
+
+      # Stops the connection without sending the explicit disconnect frame.
+      #
+      # @return [DhanHQ::WS::Connection] self.
+      def stop
+        @stop = true
+        @stopping = true
+        if @ws
+          begin
+            @ws.close
+          rescue StandardError
+          end
+        end
+        self
+      end
+
+      # Sends the disconnect frame (RequestCode 12) and closes the socket.
+      #
+      # @return [DhanHQ::WS::Connection] self.
+      def disconnect!
+        @stop = true
+        @stopping = true
+        begin
+          send_disconnect
+        rescue StandardError
+        ensure
+          @ws&.close
+        end
+        self
+      end
+
+      # Indicates whether the underlying socket is currently open.
+      #
+      # @return [Boolean]
+      def open?
+        @ws && @ws.instance_variable_get(:@driver)&.ready_state == 1
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def loop_run
+        backoff = 2.0
+        until @stop
+          failed = false
+          got_429 = false # rubocop:disable Naming/VariableNumber
+
+          # respect any active cool-off window
+          sleep (@cooloff_until - Time.now).ceil if @cooloff_until && Time.now < @cooloff_until
+
+          begin
+            EM.run do
+              @ws = Faye::WebSocket::Client.new(@url, nil, headers: default_headers)
+
+              @ws.on :open do |_|
+                DhanHQ.logger&.info("[DhanHQ::WS] open")
+                # re-subscribe snapshot on reconnect
+                snapshot = @state.snapshot.map do |k|
+                  seg, sid = k.split(":")
+                  { ExchangeSegment: seg, SecurityId: sid }
+                end
+                send_sub(snapshot) unless snapshot.empty?
+                @timer = EM.add_periodic_timer(0.25) { drain_and_send }
+              end
+
+              @ws.on :message do |ev|
+                @on_binary&.call(ev.data) # raw frames to decoder
+              end
+
+              @ws.on :close do |ev|
+                # If we initiated stop/disconnect, DO NOT reconnect regardless of code.
+                EM.cancel_timer(@timer) if @timer
+                @timer = nil
+                msg = "[DhanHQ::WS] close #{ev.code} #{ev.reason}"
+                DhanHQ.logger&.warn(msg)
+
+                if @stopping
+                  failed = false
+                else
+                  failed  = (ev.code != 1000)
+                  got_429 = ev.reason.to_s.include?("429")
+                end
+                EM.stop
+              end
+
+              @ws.on :error do |ev|
+                DhanHQ.logger&.error("[DhanHQ::WS] error #{ev.message}")
+                failed = true
+              end
+            end
+          rescue StandardError => e
+            DhanHQ.logger&.error("[DhanHQ::WS] 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] cooling off #{COOL_OFF_429}s due to 429")
+            end
+
+            if failed
+              # exponential backoff with jitter
+              sleep_time = [backoff, MAX_BACKOFF].min
+              jitter = rand(0.2 * sleep_time)
+              DhanHQ.logger&.warn("[DhanHQ::WS] reconnecting in #{(sleep_time + jitter).round(1)}s")
+              sleep(sleep_time + jitter)
+              backoff *= 2.0
+            else
+              backoff = 2.0 # reset only after a clean session end
+            end
+          end
+        end
+      end
+
+      def default_headers
+        { "User-Agent" => "dhanhq-ruby/#{defined?(DhanHQ::VERSION) ? DhanHQ::VERSION : "dev"} Ruby/#{RUBY_VERSION}" }
+      end
+
+      def drain_and_send
+        cmds = @bus.drain
+        return if cmds.empty?
+
+        subs, unsubs = cmds.partition { |c| c.op == :sub }
+
+        unless subs.empty?
+          list     = uniq(flatten(subs.map(&:payload)))
+          new_only = @state.want_sub(list)
+          unless new_only.empty?
+            send_sub(new_only)
+            @state.mark_subscribed!(new_only)
+          end
+        end
+
+        return if unsubs.empty?
+
+        list       = uniq(flatten(unsubs.map(&:payload)))
+        exist_only = @state.want_unsub(list)
+        return if exist_only.empty?
+
+        send_unsub(exist_only)
+        @state.mark_unsubscribed!(exist_only)
+      end
+
+      def send_sub(list)
+        return if list.empty?
+
+        list.each_slice(100) do |chunk|
+          payload = { RequestCode: SUB_CODES.fetch(@mode), InstrumentCount: chunk.size, InstrumentList: chunk }
+          DhanHQ.logger&.info("[DhanHQ::WS] SUB -> +#{chunk.size} (total=#{list.size})")
+          @ws.send(payload.to_json)
+        end
+      end
+
+      def send_unsub(list)
+        return if list.empty?
+
+        list.each_slice(100) do |chunk|
+          payload = { RequestCode: UNSUB_CODES.fetch(@mode), InstrumentCount: chunk.size, InstrumentList: chunk }
+          DhanHQ.logger&.info("[DhanHQ::WS] UNSUB -> -#{chunk.size} (total=#{list.size})")
+          @ws.send(payload.to_json)
+        end
+      end
+
+      def send_disconnect
+        return unless @ws
+
+        payload = { RequestCode: 12 } # per Dhan: Disconnect Feed
+        DhanHQ.logger&.info("[DhanHQ::WS] DISCONNECT -> #{payload}")
+        @ws.send(payload.to_json)
+      rescue StandardError => e
+        DhanHQ.logger&.debug("[DhanHQ::WS] send_disconnect error #{e.class}: #{e.message}")
+      end
+
+      def flatten(a) = a.flatten
+
+      def uniq(list)
+        seen = {}
+        list.each_with_object([]) do |i, out|
+          k = "#{i[:ExchangeSegment]}:#{i[:SecurityId]}"
+          next if seen[k]
+
+          out << i
+          seen[k] = true
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/ws/decoder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "websocket_packet_parser"
+require_relative "segments"
+
+module DhanHQ
+  module WS
+    # Translates the binary WebSocket frames into Ruby hashes that can be
+    # consumed by client code.
+    class Decoder
+      # Mapping of feed response codes to semantic event kinds.
+      FEED_KIND = {
+        2 => :ticker, 4 => :quote, 5 => :oi, 6 => :prev_close, 8 => :full, 50 => :disconnect, 41 => :depth_bid, 51 => :depth_ask
+      }.freeze
+
+      # Parses a binary packet and returns a normalized hash representation.
+      #
+      # @param binary [String] Raw WebSocket frame payload.
+      # @return [Hash, nil] Normalized tick data or nil when the packet should
+      #   be ignored.
+      def self.decode(binary)
+        pkt = WebsocketPacketParser.new(binary).parse
+        return nil if pkt.nil? || pkt.empty?
+
+        kind   = FEED_KIND[pkt[:feed_response_code]] || :unknown
+        segstr = Segments.from_code(pkt[:exchange_segment])
+        sid    = pkt[:security_id].to_s
+
+        # pp pkt
+        case kind
+        when :ticker
+          {
+            kind: :ticker, segment: segstr, security_id: sid,
+            ltp: pkt[:ltp].to_f, ts: pkt[:ltt].to_i
+          }
+        when :quote
+          {
+            kind: :quote, segment: segstr, security_id: sid,
+            ltp: pkt[:ltp].to_f, ts: pkt[:ltt].to_i, atp: pkt[:atp].to_f,
+            vol: pkt[:volume].to_i, ts_buy_qty: pkt[:total_buy_qty].to_i, ts_sell_qty: pkt[:total_sell_qty].to_i,
+            day_open: pkt[:day_open]&.to_f, day_high: pkt[:day_high]&.to_f, day_low: pkt[:day_low]&.to_f, day_close: pkt[:day_close]&.to_f
+          }
+        when :full
+          out = {
+            kind: :full, segment: segstr, security_id: sid,
+            ltp: pkt[:ltp].to_f, ts: pkt[:ltt].to_i, atp: pkt[:atp].to_f,
+            vol: pkt[:volume].to_i, ts_buy_qty: pkt[:total_buy_qty].to_i, ts_sell_qty: pkt[:total_sell_qty].to_i,
+            oi: pkt[:open_interest]&.to_i, oi_high: pkt[:highest_open_interest]&.to_i, oi_low: pkt[:lowest_open_interest]&.to_i,
+            day_open: pkt[:day_open]&.to_f, day_high: pkt[:day_high]&.to_f, day_low: pkt[:day_low]&.to_f, day_close: pkt[:day_close]&.to_f
+          }
+          # First depth level (if present)
+          if (md = pkt[:market_depth]).respond_to?(:[]) && md[0]
+            lvl = md[0]
+            out[:bid] = lvl.respond_to?(:bid_price) ? lvl.bid_price.to_f : nil
+            out[:ask] = lvl.respond_to?(:ask_price) ? lvl.ask_price.to_f : nil
+          end
+          out
+        when :oi
+          { kind: :oi, segment: segstr, security_id: sid, oi: pkt[:open_interest].to_i }
+        when :prev_close
+          { kind: :prev_close, segment: segstr, security_id: sid, prev_close: pkt[:prev_close].to_f,
+            oi_prev: pkt[:oi_prev].to_i }
+        when :depth_bid, :depth_ask
+          {
+            kind: kind, segment: segstr, security_id: sid,
+            bid_quantity: pkt[:bid_quantity], ask_quantity: pkt[:ask_quantity],
+            no_of_bid_orders: pkt[:no_of_bid_orders], no_of_ask_orders: pkt[:no_of_ask_orders],
+            bid: pkt[:bid_price], ask: pkt[:ask_price]
+          }
+        when :disconnect
+          DhanHQ.logger&.warn("[DhanHQ::WS] disconnect code=#{pkt[:disconnection_code]} seg=#{segstr} sid=#{sid}")
+          nil
+        else
+          DhanHQ.logger&.debug("[DhanHQ::WS] unknown feed kind code=#{pkt[:feed_response_code]}")
+          nil
+        end
+      rescue StandardError => e
+        DhanHQ.logger&.debug("[DhanHQ::WS::Decoder] #{e.class}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require_relative "connection"
+
+module DhanHQ
+  module WS
+    module Orders
+      class Client
+        def initialize(url: nil)
+          @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
+          @started   = Concurrent::AtomicBoolean.new(false)
+          cfg        = DhanHQ.configuration
+          @url       = url || cfg.ws_order_url
+        end
+
+        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.start
+          DhanHQ::WS::Registry.register(self) if defined?(DhanHQ::WS::Registry)
+          self
+        end
+
+        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
+
+        def disconnect!
+          @conn&.disconnect!
+        end
+
+        def on(event, &blk)
+          @callbacks[event] << blk
+          self
+        end
+
+        private
+
+        def emit(event, payload)
+          list = begin
+            @callbacks[event]
+          rescue StandardError
+            []
+          end
+          list.each { |cb| cb.call(payload) }
+        end
+      end
+    end
+  end
+end