DhanHQ 2.1.8 → 2.2.0

data/lib/DhanHQ/models/trade.rb

@@ -3,11 +3,35 @@
 module DhanHQ
   module Models
     ##
-    # Represents a single trade.
-    # Supports three main API endpoints:
-    # 1. GET /v2/trades - Current day trades
-    # 2. GET /v2/trades/{order-id} - Trades for specific order
-    # 3. GET /v2/trades/{from-date}/{to-date}/{page} - Historical trades
+    # Model for retrieving trade execution details.
+    #
+    # The Trade Book API lets you retrieve an array of all trades executed in a day.
+    # You can also fetch trade details for a specific order ID, which is useful during
+    # partial trades or Bracket/Cover Orders. Additionally, you can retrieve detailed
+    # trade history for all orders within a particular time frame.
+    #
+    # @example Fetch all trades for today
+    #   trades = DhanHQ::Models::Trade.today
+    #   trades.each do |trade|
+    #     puts "#{trade.trading_symbol}: #{trade.traded_quantity} @ ₹#{trade.traded_price}"
+    #     puts "Total Value: ₹#{trade.total_value}, Charges: ₹#{trade.total_charges}"
+    #   end
+    #
+    # @example Fetch trades for a specific order
+    #   trade = DhanHQ::Models::Trade.find_by_order_id("112111182045")
+    #   if trade
+    #     puts "Traded: #{trade.traded_quantity} @ ₹#{trade.traded_price}"
+    #   end
+    #
+    # @example Fetch historical trades
+    #   trades = DhanHQ::Models::Trade.history(
+    #     from_date: "2022-12-01",
+    #     to_date: "2022-12-31",
+    #     page: 0
+    #   )
+    #   total_value = trades.sum(&:total_value)
+    #   puts "Total traded value: ₹#{total_value}"
+    #
     class Trade < BaseModel
       HTTP_PATH = "/v2/trades"
 
@@ -22,22 +46,66 @@ module DhanHQ
 
       class << self
         ##
-        # Resource for current day tradebook APIs
+        # Provides a shared instance of the Trades resource for current day tradebook APIs.
+        #
+        # @return [DhanHQ::Resources::Trades] The Trades resource client instance
         def tradebook_resource
           @tradebook_resource ||= DhanHQ::Resources::Trades.new
         end
 
         ##
-        # Resource for historical trade data
+        # Provides a shared instance of the Statements resource for historical trade data.
+        #
+        # @return [DhanHQ::Resources::Statements] The Statements resource client instance
         def statements_resource
           @statements_resource ||= DhanHQ::Resources::Statements.new
         end
 
         ##
-        # Fetch current day trades
-        # GET /v2/trades
+        # Retrieves all trades executed during the current trading day.
+        #
+        # Fetches an array of all trades executed in the day. This is useful for
+        # tracking daily execution activity and analyzing trade performance.
+        #
+        # @return [Array<Trade>] Array of Trade objects. Returns empty array if no trades exist.
+        #   Each Trade object contains (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:order_id** [String] Order-specific identification generated by Dhan
+        #   - **:exchange_order_id** [String] Order-specific identification generated by exchange
+        #   - **:exchange_trade_id** [String] Trade-specific identification generated by exchange
+        #   - **:transaction_type** [String] The trading side of transaction. "BUY" or "SELL"
+        #   - **:exchange_segment** [String] Exchange segment of instrument
+        #   - **:product_type** [String] Product type. Valid values: "CNC", "INTRADAY",
+        #     "MARGIN", "MTF", "CO", "BO"
+        #   - **:order_type** [String] Order type. Valid values: "LIMIT", "MARKET",
+        #     "STOP_LOSS", "STOP_LOSS_MARKET"
+        #   - **:trading_symbol** [String] Trading symbol of the instrument
+        #   - **:security_id** [String] Exchange standard ID for each scrip
+        #   - **:traded_quantity** [Integer] Number of shares executed
+        #   - **:traded_price** [Float] Price at which trade is executed
+        #   - **:create_time** [String] Time at which the order is created
+        #   - **:update_time** [String] Time at which the last activity happened
+        #   - **:exchange_time** [String] Time at which order reached at exchange
+        #   - **:drv_expiry_date** [String, nil] For F&O, expiry date of contract
+        #   - **:drv_option_type** [String, nil] Type of Option. "CALL" or "PUT"
+        #   - **:drv_strike_price** [Float] For Options, Strike Price
+        #
+        # @example Fetch and analyze today's trades
+        #   trades = DhanHQ::Models::Trade.today
+        #   buy_trades = trades.select(&:buy?)
+        #   sell_trades = trades.select(&:sell?)
+        #   puts "Buy trades: #{buy_trades.count}, Sell trades: #{sell_trades.count}"
+        #   total_value = trades.sum(&:total_value)
+        #   puts "Total traded value: ₹#{total_value}"
+        #
+        # @example Calculate P&L for today
+        #   trades = DhanHQ::Models::Trade.today
+        #   buy_value = trades.select(&:buy?).sum(&:total_value)
+        #   sell_value = trades.select(&:sell?).sum(&:total_value)
+        #   total_charges = trades.sum(&:total_charges)
+        #   pnl = sell_value - buy_value - total_charges
+        #   puts "P&L: ₹#{pnl}"
         #
-        # @return [Array<Trade>] Array of trades executed today
         def today
           response = tradebook_resource.all
           return [] unless response.is_a?(Array)
@@ -46,11 +114,28 @@ module DhanHQ
         end
 
         ##
-        # Fetch trades for a specific order ID (current day)
-        # GET /v2/trades/{order-id}
+        # Retrieves trade details for a specific order ID (current day).
+        #
+        # Fetches all trades generated for a particular order ID. This is especially useful
+        # during partial trades or Bracket/Cover Orders where traders may get confused
+        # reading trades from the tradebook. The response includes all trades generated
+        # for the specified order ID.
+        #
+        # @param order_id [String] Order-specific identification generated by Dhan
         #
-        # @param order_id [String] The order ID to fetch trades for
-        # @return [Trade, nil] Trade object or nil if not found
+        # @return [Trade, nil] Trade object with trade details if found, nil otherwise.
+        #   Response structure is the same as {today}.
+        #
+        # @example Fetch trade for an order
+        #   trade = DhanHQ::Models::Trade.find_by_order_id("112111182045")
+        #   if trade
+        #     puts "Order: #{trade.order_id}"
+        #     puts "Traded: #{trade.traded_quantity} @ ₹#{trade.traded_price}"
+        #     puts "Symbol: #{trade.trading_symbol}"
+        #     puts "Time: #{trade.exchange_time}"
+        #   end
+        #
+        # @raise [DhanHQ::ValidationError] If order_id validation fails
         def find_by_order_id(order_id)
           # Validate input
           contract = DhanHQ::Contracts::TradeByOrderIdContract.new
@@ -68,13 +153,61 @@ module DhanHQ
         end
 
         ##
-        # Fetch historical trades within the given date range and page
-        # GET /v2/trades/{from-date}/{to-date}/{page}
+        # Retrieves detailed trade history for all orders within a specified time frame.
         #
-        # @param from_date [String] Start date in YYYY-MM-DD format
-        # @param to_date   [String] End date in YYYY-MM-DD format
-        # @param page      [Integer] Page number (default: 0)
-        # @return [Array<Trade>] Array of historical trades
+        # Fetches paginated trade history data with comprehensive charge breakdowns.
+        # The response includes detailed information about SEBI tax, STT, brokerage charges,
+        # service tax, exchange transaction charges, and stamp duty for each trade.
+        #
+        # @param from_date [String] (required) Start date in "YYYY-MM-DD" format
+        # @param to_date [String] (required) End date in "YYYY-MM-DD" format
+        # @param page [Integer] (default: 0) Page number for paginated results. Pass 0 for first page
+        #
+        # @return [Array<Trade>] Array of historical Trade objects. Returns empty array if no trades found.
+        #   Each Trade object contains all fields from {today} plus additional charge details:
+        #   - **:custom_symbol** [String] Trading Symbol as per Dhan
+        #   - **:isin** [String] Universal standard ID for each scrip (International Securities Identification Number)
+        #   - **:instrument** [String] Type of Instrument. "EQUITY" or "DERIVATIVES"
+        #   - **:sebi_tax** [String] SEBI Turnover Charges
+        #   - **:stt** [String] Securities Transactions Tax
+        #   - **:brokerage_charges** [String] Brokerage charges by Dhan
+        #   - **:service_tax** [String] Applicable Service Tax
+        #   - **:exchange_transaction_charges** [String] Exchange Transaction Charge
+        #   - **:stamp_duty** [String] Stamp Duty Charges
+        #
+        # @example Fetch historical trades for a month
+        #   trades = DhanHQ::Models::Trade.history(
+        #     from_date: "2022-12-01",
+        #     to_date: "2022-12-31",
+        #     page: 0
+        #   )
+        #   puts "Total trades: #{trades.count}"
+        #
+        # @example Calculate total charges for historical period
+        #   trades = DhanHQ::Models::Trade.history(
+        #     from_date: "2022-12-01",
+        #     to_date: "2022-12-31"
+        #   )
+        #   total_charges = trades.sum(&:total_charges)
+        #   total_brokerage = trades.sum { |t| t.brokerage_charges.to_f }
+        #   puts "Total Charges: ₹#{total_charges}"
+        #   puts "Total Brokerage: ₹#{total_brokerage}"
+        #
+        # @example Paginate through historical trades
+        #   page = 0
+        #   loop do
+        #     trades = DhanHQ::Models::Trade.history(
+        #       from_date: "2022-12-01",
+        #       to_date: "2022-12-31",
+        #       page: page
+        #     )
+        #     break if trades.empty?
+        #
+        #     puts "Page #{page}: #{trades.count} trades"
+        #     page += 1
+        #   end
+        #
+        # @raise [DhanHQ::ValidationError] If date format or page validation fails
         def history(from_date:, to_date:, page: 0)
           validate_history_params(from_date, to_date, page)
 
@@ -91,6 +224,16 @@ module DhanHQ
 
         private
 
+        ##
+        # Validates parameters for historical trade queries.
+        #
+        # @param from_date [String] Start date in YYYY-MM-DD format
+        # @param to_date [String] End date in YYYY-MM-DD format
+        # @param page [Integer] Page number
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails
+        #
+        # @api private
         def validate_history_params(from_date, to_date, page)
           contract = DhanHQ::Contracts::TradeHistoryContract.new
           validation_result = contract.call(from_date: from_date, to_date: to_date, page: page)
@@ -100,48 +243,131 @@ module DhanHQ
           raise DhanHQ::ValidationError, "Invalid parameters: #{validation_result.errors.to_h}"
         end
 
-        # Alias for backward compatibility
+        # Alias for backward compatibility with historical trades
+        # @api private
         alias all history
       end
 
       ##
-      # Trade objects are read-only, so no validation contract needed
+      # Trade objects are read-only, so no validation contract needed.
+      #
+      # @return [nil] Always returns nil as trades are read-only
+      #
+      # @api private
       def validation_contract
         nil
       end
 
       ##
-      # Helper methods for trade data
+      # Checks if the trade is a BUY transaction.
+      #
+      # @return [Boolean] true if transaction_type is "BUY", false otherwise
+      #
+      # @example
+      #   trade = DhanHQ::Models::Trade.today.first
+      #   if trade.buy?
+      #     puts "This is a buy trade"
+      #   end
+      #
       def buy?
         transaction_type == "BUY"
       end
 
+      ##
+      # Checks if the trade is a SELL transaction.
+      #
+      # @return [Boolean] true if transaction_type is "SELL", false otherwise
+      #
+      # @example
+      #   trade = DhanHQ::Models::Trade.today.first
+      #   if trade.sell?
+      #     puts "This is a sell trade"
+      #   end
+      #
       def sell?
         transaction_type == "SELL"
       end
 
+      ##
+      # Checks if the trade instrument is EQUITY.
+      #
+      # @return [Boolean] true if instrument is "EQUITY", false otherwise
+      #
+      # @example
+      #   trades = DhanHQ::Models::Trade.today
+      #   equity_trades = trades.select(&:equity?)
+      #   puts "Equity trades: #{equity_trades.count}"
+      #
       def equity?
         instrument == "EQUITY"
       end
 
+      ##
+      # Checks if the trade instrument is DERIVATIVES.
+      #
+      # @return [Boolean] true if instrument is "DERIVATIVES", false otherwise
+      #
+      # @example
+      #   trades = DhanHQ::Models::Trade.today
+      #   derivative_trades = trades.select(&:derivative?)
+      #   puts "Derivative trades: #{derivative_trades.count}"
+      #
       def derivative?
         instrument == "DERIVATIVES"
       end
 
+      ##
+      # Checks if the trade is an option (CALL or PUT).
+      #
+      # @return [Boolean] true if drv_option_type is "CALL" or "PUT", false otherwise
+      #
+      # @example
+      #   trades = DhanHQ::Models::Trade.today
+      #   option_trades = trades.select(&:option?)
+      #   puts "Option trades: #{option_trades.count}"
+      #
       def option?
         %w[CALL PUT].include?(drv_option_type)
       end
 
+      ##
+      # Checks if the trade is a CALL option.
+      #
+      # @return [Boolean] true if drv_option_type is "CALL", false otherwise
+      #
+      # @example
+      #   trades = DhanHQ::Models::Trade.today
+      #   call_trades = trades.select(&:call_option?)
+      #   puts "Call option trades: #{call_trades.count}"
+      #
       def call_option?
         drv_option_type == "CALL"
       end
 
+      ##
+      # Checks if the trade is a PUT option.
+      #
+      # @return [Boolean] true if drv_option_type is "PUT", false otherwise
+      #
+      # @example
+      #   trades = DhanHQ::Models::Trade.today
+      #   put_trades = trades.select(&:put_option?)
+      #   puts "Put option trades: #{put_trades.count}"
+      #
       def put_option?
         drv_option_type == "PUT"
       end
 
       ##
-      # Calculate total trade value
+      # Calculates the total trade value (quantity × price).
+      #
+      # @return [Float] Total trade value. Returns 0 if traded_quantity or traded_price is missing
+      #
+      # @example
+      #   trade = DhanHQ::Models::Trade.today.first
+      #   puts "Trade Value: ₹#{trade.total_value}"
+      #   # => Trade Value: ₹133832.0
+      #
       def total_value
         return 0 unless traded_quantity && traded_price
 
@@ -149,7 +375,22 @@ module DhanHQ
       end
 
       ##
-      # Calculate total charges
+      # Calculates the total charges for the trade.
+      #
+      # Sums all applicable charges including SEBI tax, STT, brokerage charges,
+      # service tax, exchange transaction charges, and stamp duty.
+      #
+      # @return [Float] Total charges amount. Returns 0 if no charges are present
+      #
+      # @example
+      #   trade = DhanHQ::Models::Trade.history(
+      #     from_date: "2022-12-01",
+      #     to_date: "2022-12-31"
+      #   ).first
+      #   puts "Total Charges: ₹#{trade.total_charges}"
+      #   puts "Brokerage: ₹#{trade.brokerage_charges}"
+      #   puts "STT: ₹#{trade.stt}"
+      #
       def total_charges
         charges = [sebi_tax, stt, brokerage_charges, service_tax,
                    exchange_transaction_charges, stamp_duty].compact
@@ -157,7 +398,19 @@ module DhanHQ
       end
 
       ##
-      # Net trade value after charges
+      # Calculates the net trade value after deducting all charges.
+      #
+      # @return [Float] Net trade value (total_value - total_charges)
+      #
+      # @example
+      #   trade = DhanHQ::Models::Trade.history(
+      #     from_date: "2022-12-01",
+      #     to_date: "2022-12-31"
+      #   ).first
+      #   puts "Gross Value: ₹#{trade.total_value}"
+      #   puts "Charges: ₹#{trade.total_charges}"
+      #   puts "Net Value: ₹#{trade.net_value}"
+      #
       def net_value
         total_value - total_charges
       end

data/lib/DhanHQ/rate_limiter.rb

@@ -140,25 +140,59 @@ module DhanHQ
 
     # Spawns background threads to reset counters after each interval elapses.
     def start_cleanup_threads
+      @cleanup_threads = []
+      @shutdown = Concurrent::AtomicBoolean.new(false)
+
       # Don't create per_second cleanup thread - we handle it with timestamps
-      Thread.new do
+      @cleanup_threads << Thread.new do
         loop do
+          break if @shutdown.true?
+
           sleep(60)
-          @buckets[:per_minute]&.value = 0
+          break if @shutdown.true?
+
+          mutex.synchronize do
+            @buckets[:per_minute]&.value = 0
+          end
         end
       end
-      Thread.new do
+
+      @cleanup_threads << Thread.new do
         loop do
+          break if @shutdown.true?
+
           sleep(3600)
-          @buckets[:per_hour]&.value = 0
+          break if @shutdown.true?
+
+          mutex.synchronize do
+            @buckets[:per_hour]&.value = 0
+          end
         end
       end
-      Thread.new do
+
+      @cleanup_threads << Thread.new do
         loop do
+          break if @shutdown.true?
+
           sleep(86_400)
-          @buckets[:per_day]&.value = 0
+          break if @shutdown.true?
+
+          mutex.synchronize do
+            @buckets[:per_day]&.value = 0
+          end
         end
       end
     end
+
+    # Shuts down cleanup threads gracefully
+    def shutdown
+      return if @shutdown.true?
+
+      @shutdown.make_true
+      @cleanup_threads&.each do |thread|
+        thread&.wakeup if thread&.alive?
+        thread&.join(5) # Wait up to 5 seconds for thread to finish
+      end
+    end
   end
 end

data/lib/DhanHQ/resources/expired_options_data.rb

@@ -6,7 +6,7 @@ module DhanHQ
     # Resource for expired options data API endpoints
     class ExpiredOptionsData < BaseAPI
       API_TYPE = :data_api
-      HTTP_PATH = "/charts"
+      HTTP_PATH = "/v2/charts"
 
       ##
       # Fetch expired options data for rolling contracts

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "2.1.8"
+  VERSION = "2.2.0"
 end

data/lib/DhanHQ/ws/client.rb

@@ -27,7 +27,8 @@ module DhanHQ
         @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"
+        token = DhanHQ.configuration.resolved_access_token
+        raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
         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"
@@ -164,11 +165,16 @@ module DhanHQ
       def prune(hash) = { ExchangeSegment: hash[:ExchangeSegment], SecurityId: hash[:SecurityId] }
 
       def emit(event, payload)
-        begin
-          @callbacks[event].dup
+        # Create a frozen snapshot of callbacks to avoid modification during iteration
+        callbacks_snapshot = begin
+          @callbacks[event].dup.freeze
         rescue StandardError
-          []
-        end.each { |cb| cb.call(payload) }
+          [].freeze
+        end
+
+        callbacks_snapshot.each { |cb| cb.call(payload) }
+      rescue StandardError => e
+        DhanHQ.logger&.error("[DhanHQ::WS::Client] Error in event handler for #{event}: #{e.class} #{e.message}")
       end
 
       def install_at_exit_once!

data/lib/DhanHQ/ws/connection.rb

@@ -141,8 +141,20 @@ module DhanHQ
             end
           rescue StandardError => e
             DhanHQ.logger&.error("[DhanHQ::WS] crashed #{e.class} #{e.message}")
+            DhanHQ.logger&.error("[DhanHQ::WS] backtrace: #{e.backtrace&.first(5)&.join("\n")}")
             failed = true
+            # Reset connection state on error
+            @ws = nil
+            @timer = nil
           ensure
+            # Clean up EventMachine resources
+            begin
+              EM.cancel_timer(@timer) if @timer
+              @timer = nil
+            rescue StandardError => e
+              DhanHQ.logger&.debug("[DhanHQ::WS] cleanup error: #{e.message}")
+            end
+
             break if @stop
 
             if got_429
@@ -154,11 +166,13 @@ module DhanHQ
               # 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")
+              DhanHQ.logger&.warn("[DhanHQ::WS] reconnecting in #{(sleep_time + jitter).round(1)}s (backoff: #{backoff.round(1)}s)")
               sleep(sleep_time + jitter)
               backoff *= 2.0
             else
-              backoff = 2.0 # reset only after a clean session end
+              # Reset backoff only after a clean session end (normal close with code 1000)
+              backoff = 2.0
+              DhanHQ.logger&.debug("[DhanHQ::WS] backoff reset to 2.0s after clean session end")
             end
           end
         end

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

@@ -80,7 +80,8 @@ module DhanHQ
         # @param config [Configuration] DhanHQ configuration
         # @return [String] WebSocket URL
         def build_market_depth_url(config)
-          token = config.access_token or raise "DhanHQ.access_token not set"
+          token = config.resolved_access_token
+          raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
           cid = config.client_id or raise "DhanHQ.client_id not set"
           depth_level = config.market_depth_level || 20 # Default to 20 level depth
 

data/lib/DhanHQ/ws/market_depth.rb

@@ -17,9 +17,9 @@ module DhanHQ
       # @param options [Hash] Connection options
       # @param block [Proc] Callback for depth updates
       # @return [Client] WebSocket client instance
-      def connect(symbols: [], **options, &block)
-        client = Client.new(symbols: symbols, **options)
-        client.on(:depth_update, &block) if block_given?
+      def connect(symbols: [], **, &)
+        client = Client.new(symbols: symbols, **)
+        client.on(:depth_update, &) if block_given?
         client.start
       end
 
@@ -28,8 +28,8 @@ module DhanHQ
       # @param symbols [Array<String>] Symbols to subscribe to
       # @param options [Hash] Connection options
       # @return [Client] New client instance
-      def client(symbols: [], **options)
-        Client.new(symbols: symbols, **options)
+      def client(symbols: [], **)
+        Client.new(symbols: symbols, **)
       end
 
       ##
@@ -38,8 +38,8 @@ module DhanHQ
       # @param handlers [Hash] Event handlers
       # @param options [Hash] Connection options
       # @return [Client] Started client instance
-      def connect_with_handlers(symbols: [], handlers: {}, **options)
-        client = Client.new(symbols: symbols, **options).start
+      def connect_with_handlers(symbols: [], handlers: {}, **)
+        client = Client.new(symbols: symbols, **).start
 
         handlers.each do |event, handler|
           client.on(event, &handler)
@@ -54,8 +54,8 @@ module DhanHQ
       # @param options [Hash] Connection options
       # @param block [Proc] Callback for depth updates
       # @return [Client] Started client instance
-      def subscribe(symbols:, **options, &block)
-        connect(symbols: symbols, **options, &block)
+      def subscribe(symbols:, **, &)
+        connect(symbols: symbols, **, &)
       end
 
       ##
@@ -64,9 +64,9 @@ module DhanHQ
       # @param options [Hash] Connection options
       # @param block [Proc] Callback for snapshot data
       # @return [Client] Started client instance
-      def snapshot(symbols:, **options, &block)
-        client = Client.new(symbols: symbols, **options)
-        client.on(:depth_snapshot, &block) if block_given?
+      def snapshot(symbols:, **, &)
+        client = Client.new(symbols: symbols, **)
+        client.on(:depth_snapshot, &) if block_given?
         client.start
       end
     end