DhanHQ 2.1.0

data/lib/DhanHQ/ws/websocket_packet_parser.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+require_relative "packets/header"
+require_relative "packets/ticker_packet"
+require_relative "packets/quote_packet"
+require_relative "packets/full_packet"
+require_relative "packets/oi_packet"
+require_relative "packets/prev_close_packet"
+require_relative "packets/disconnect_packet"
+require_relative "packets/index_packet"
+require_relative "packets/market_status_packet"
+# optional:
+require_relative "packets/depth_delta_packet"
+
+module DhanHQ
+  module WS
+    # Parses raw WebSocket frames using the binary packet definitions.
+    class WebsocketPacketParser
+      # Numeric feed codes emitted by the streaming service.
+      RESPONSE_CODES = {
+        index: 1,
+        ticker: 2,
+        quote: 4,
+        oi: 5,
+        prev_close: 6,
+        full: 8,
+        depth_bid: 41,
+        depth_ask: 51,
+        disconnect: 50
+      }.freeze
+
+      attr_reader :binary_data, :binary_stream, :header
+
+      def initialize(binary_data)
+        @binary_data   = binary_data
+        @header        = Packets::Header.read(@binary_data) # 8 bytes header
+        @binary_stream = StringIO.new(@binary_data.byteslice(8..) || "".b) # payload only
+      end
+
+      # Parses the supplied binary frame and returns a normalized hash.
+      #
+      # @return [Hash]
+      def parse
+        body =
+          case header.feed_response_code
+          when RESPONSE_CODES[:index]       then parse_index
+          when RESPONSE_CODES[:ticker]      then parse_ticker
+          when RESPONSE_CODES[:quote]       then parse_quote
+          when RESPONSE_CODES[:oi]          then parse_oi
+          when RESPONSE_CODES[:prev_close]  then parse_prev_close
+          when RESPONSE_CODES[:market_status] then parse_market_status
+          when RESPONSE_CODES[:full]        then parse_full
+          when RESPONSE_CODES[:depth_bid]   then parse_depth(:bid)
+          when RESPONSE_CODES[:depth_ask]   then parse_depth(:ask)
+          when RESPONSE_CODES[:disconnect]  then parse_disconnect
+          else
+            DhanHQ.logger&.debug("[WS::Parser] Unknown feed code=#{header.feed_response_code}")
+            {}
+          end
+
+        {
+          feed_response_code: header.feed_response_code,
+          message_length: header.message_length,
+          exchange_segment: header.exchange_segment, # numeric (0/1/2/…)
+          security_id: header.security_id
+        }.merge(body)
+      rescue StandardError => e
+        DhanHQ.logger.error "[WS::Parser] ❌ #{e.class}: #{e.message}"
+        {}
+      end
+
+      private
+
+      def parse_index
+        rec = Packets::IndexPacket.new(@binary_stream.string)
+        { index_raw: rec.raw } # keep raw until official layout is known
+      end
+
+      def parse_market_status
+        rec = Packets::MarketStatusPacket.new(@binary_stream.string)
+        { market_status_raw: rec.raw } # keep raw until official layout is known
+      end
+
+      def parse_ticker
+        rec = Packets::TickerPacket.read(@binary_stream.string)
+        { ltp: rec.ltp, ltt: rec.ltt }
+      end
+
+      def parse_quote
+        rec = Packets::QuotePacket.read(@binary_stream.string)
+
+        {
+          ltp: rec.ltp,
+          last_trade_qty: rec.last_trade_qty,
+          ltt: rec.ltt,
+          atp: rec.atp,
+          volume: rec.volume,
+          total_sell_qty: rec.total_sell_qty,
+          total_buy_qty: rec.total_buy_qty,
+          day_open: rec.day_open,
+          day_close: rec.day_close,
+          day_high: rec.day_high,
+          day_low: rec.day_low
+        }
+      end
+
+      def parse_full
+        rec = Packets::FullPacket.read(@binary_stream.string)
+        {
+          ltp: rec.ltp,
+          last_trade_qty: rec.last_trade_qty,
+          ltt: rec.ltt,
+          atp: rec.atp,
+          volume: rec.volume,
+          total_sell_qty: rec.total_sell_qty,
+          total_buy_qty: rec.total_buy_qty,
+          open_interest: rec.open_interest,
+          highest_open_interest: rec.highest_oi,
+          lowest_open_interest: rec.lowest_oi,
+          day_open: rec.day_open,
+          day_close: rec.day_close,
+          day_high: rec.day_high,
+          day_low: rec.day_low,
+          market_depth: rec.market_depth
+        }
+      end
+
+      def parse_oi
+        rec = Packets::OiPacket.read(@binary_stream.string)
+        { open_interest: rec.open_interest }
+      end
+
+      def parse_prev_close
+        rec = Packets::PrevClosePacket.read(@binary_stream.string)
+        { prev_close: rec.prev_close, oi_prev: rec.oi_prev }
+      end
+
+      # depth_bid / depth_ask incremental
+      def parse_depth(side)
+        rec = Packets::DepthDeltaPacket.read(@binary_stream.string)
+        {
+          depth_side: side,
+          bid_quantity: rec.bid_quantity,
+          ask_quantity: rec.ask_quantity,
+          no_of_bid_orders: rec.no_of_bid_orders,
+          no_of_ask_orders: rec.no_of_ask_orders,
+          bid_price: rec.bid_price,
+          ask_price: rec.ask_price
+        }
+      end
+
+      def parse_disconnect
+        {
+          disconnection_code: binary_stream.read(2).unpack1("s>")
+        }
+      end
+
+      def debug_log(data)
+        DhanHQ.logger.debug { "[WS::Parser] Parsed: #{data.inspect}" }
+      end
+    end
+  end
+end

data/lib/DhanHQ/ws.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "ws/client"
+require_relative "ws/orders"
+
+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.
+  module WS
+    # Establishes a WebSocket connection and yields decoded ticks.
+    #
+    # @example Subscribe to ticker updates
+    #   DhanHQ::WS.connect(mode: :ticker) do |tick|
+    #     puts tick.inspect
+    #   end
+    #
+    # @param mode [Symbol] Desired feed mode (:ticker, :quote, :full).
+    # @yield [tick]
+    # @yieldparam tick [Hash] A decoded tick emitted by the streaming API.
+    # @return [DhanHQ::WS::Client] The underlying WebSocket client instance.
+    def self.connect(mode: :ticker, &on_tick)
+      Client.new(mode: mode).start.on(:tick, &on_tick)
+    end
+
+    # Disconnects every WebSocket client created in the current process.
+    #
+    # Useful when a long running script needs to ensure all connections are
+    # closed (e.g., in signal handlers or +at_exit+ hooks).
+    #
+    # @return [void]
+    def self.disconnect_all_local!
+      Registry.stop_all
+    end
+  end
+end

data/lib/DhanHQ.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "dotenv/load"
+require "logger"
+
+# Helper Methods
+require_relative "DhanHQ/helpers/api_helper"
+require_relative "DhanHQ/helpers/attribute_helper"
+require_relative "DhanHQ/helpers/validation_helper"
+require_relative "DhanHQ/helpers/request_helper"
+require_relative "DhanHQ/helpers/response_helper"
+require_relative "DhanHQ/json_loader"
+
+require_relative "DhanHQ/core/base_api"
+require_relative "DhanHQ/core/base_resource"
+require_relative "DhanHQ/core/base_model"
+require_relative "DhanHQ/core/error_handler"
+
+require_relative "DhanHQ/version"
+require_relative "DhanHQ/errors"
+require_relative "DhanHQ/error_object"
+
+require_relative "DhanHQ/client"
+require_relative "DhanHQ/configuration"
+require_relative "DhanHQ/rate_limiter"
+
+# Contracts
+require_relative "DhanHQ/contracts/base_contract"
+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"
+
+# Resources
+require_relative "DhanHQ/resources/option_chain"
+require_relative "DhanHQ/resources/orders"
+require_relative "DhanHQ/resources/forever_orders"
+require_relative "DhanHQ/resources/super_orders"
+require_relative "DhanHQ/resources/funds"
+require_relative "DhanHQ/resources/holdings"
+require_relative "DhanHQ/resources/positions"
+require_relative "DhanHQ/resources/statements"
+require_relative "DhanHQ/resources/trades"
+require_relative "DhanHQ/resources/historical_data"
+require_relative "DhanHQ/resources/margin_calculator"
+require_relative "DhanHQ/resources/market_feed"
+require_relative "DhanHQ/resources/edis"
+require_relative "DhanHQ/resources/kill_switch"
+require_relative "DhanHQ/resources/profile"
+
+# Models
+require_relative "DhanHQ/models/order"
+require_relative "DhanHQ/models/funds"
+require_relative "DhanHQ/models/option_chain"
+require_relative "DhanHQ/models/forever_order"
+require_relative "DhanHQ/models/super_order"
+require_relative "DhanHQ/models/historical_data"
+require_relative "DhanHQ/models/market_feed"
+require_relative "DhanHQ/models/position"
+require_relative "DhanHQ/models/holding"
+require_relative "DhanHQ/models/ledger_entry"
+require_relative "DhanHQ/models/trade"
+require_relative "DhanHQ/models/margin"
+require_relative "DhanHQ/models/edis"
+require_relative "DhanHQ/models/kill_switch"
+require_relative "DhanHQ/models/profile"
+
+require_relative "DhanHQ/constants"
+require_relative "DhanHQ/ws"
+require_relative "DhanHQ/ws/singleton_lock"
+
+# The top-level module for the DhanHQ client library.
+#
+# Provides configuration management for setting credentials and API-related settings.
+module DhanHQ
+  class Error < StandardError; end
+
+  class << self
+    # Default REST API host used when no custom base URL is provided.
+    #
+    # @return [String]
+    BASE_URL = "https://api.dhan.co/v2"
+    # The current configuration instance.
+    #
+    # @return [DhanHQ::Configuration, nil] The current configuration or `nil` if not set.
+    attr_accessor :configuration
+
+    attr_writer :logger
+
+    # Configures the DhanHQ client with user-defined settings.
+    #
+    # @example
+    #   DhanHQ.configure do |config|
+    #     config.access_token = 'your_access_token'
+    #     config.client_id = 'your_client_id'
+    #   end
+    #
+    # @yieldparam [DhanHQ::Configuration] configuration The configuration object.
+    # @return [void]
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+      self.logger ||= Logger.new($stdout, level: Logger::INFO)
+    end
+
+    # default logger so calls like DhanHQ.logger&.info never explode
+    # Accessor for the logger instance used by the SDK.
+    #
+    # @return [Logger] The configured logger, defaulting to STDOUT at INFO level.
+    def logger
+      @logger ||= Logger.new($stdout, level: Logger::INFO)
+    end
+
+    # Configures the DhanHQ client using environment variables.
+    #
+    # When credentials are injected via `ACCESS_TOKEN` and `CLIENT_ID` this helper
+    # can be used to initialise a configuration without a block.
+    #
+    # @example
+    #   DhanHQ.configure_with_env
+    #
+    # @return [void]
+    def configure_with_env
+      self.configuration ||= Configuration.new
+      configuration.access_token = ENV.fetch("ACCESS_TOKEN", nil)
+      configuration.client_id = ENV.fetch("CLIENT_ID", nil)
+      configuration.base_url = ENV.fetch("DHAN_BASE_URL", BASE_URL)
+      configuration.ws_version = ENV.fetch("DHAN_WS_VERSION", configuration.ws_version || 2).to_i
+      configuration.ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", configuration.ws_order_url)
+      configuration.ws_user_type = ENV.fetch("DHAN_WS_USER_TYPE", configuration.ws_user_type)
+      configuration.partner_id = ENV.fetch("DHAN_PARTNER_ID", configuration.partner_id)
+      configuration.partner_secret = ENV.fetch("DHAN_PARTNER_SECRET", configuration.partner_secret)
+    end
+  end
+end