DhanHQ 2.1.7 → 2.1.10

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

@@ -15,13 +15,31 @@ module DhanHQ
                          per_day: Float::INFINITY }
     }.freeze
 
+    # Thread-safe shared rate limiters per API type
+    @shared_limiters = Concurrent::Map.new
+    @mutexes = Concurrent::Map.new
+
+    class << self
+      attr_reader :shared_limiters, :mutexes
+
+      # Get or create a shared rate limiter instance for the given API type
+      def for(api_type)
+        @shared_limiters[api_type] ||= new(api_type)
+      end
+    end
+
     # Creates a rate limiter for a given API type.
+    # Note: For proper rate limiting coordination, use RateLimiter.for(api_type) instead
+    # of RateLimiter.new(api_type) to get a shared instance.
     #
     # @param api_type [Symbol] One of the keys from {RATE_LIMITS}.
     def initialize(api_type)
       @api_type = api_type
       @buckets = Concurrent::Hash.new
       @buckets[:last_request_time] = Time.at(0) if api_type == :option_chain
+      # Track request timestamps for per-second limiting
+      @request_times = []
+      @window_start = Time.now
       initialize_buckets
       start_cleanup_threads
     end
@@ -30,34 +48,70 @@ module DhanHQ
     #
     # @return [void]
     def throttle!
-      if @api_type == :option_chain
-        last_request_time = @buckets[:last_request_time]
+      mutex.synchronize do
+        if @api_type == :option_chain
+          last_request_time = @buckets[:last_request_time]
 
-        sleep_time = 3 - (Time.now - last_request_time)
-        if sleep_time.positive?
-          if ENV["DHAN_DEBUG"] == "true"
-            puts "Sleeping for #{sleep_time.round(2)} seconds due to option_chain rate limit"
+          sleep_time = 3 - (Time.now - last_request_time)
+          if sleep_time.positive?
+            if ENV["DHAN_DEBUG"] == "true"
+              puts "Sleeping for #{sleep_time.round(2)} seconds due to option_chain rate limit"
+            end
+            sleep(sleep_time)
           end
-          sleep(sleep_time)
+
+          @buckets[:last_request_time] = Time.now
+          return
         end
 
-        @buckets[:last_request_time] = Time.now
-        return
-      end
+        # For per-second limits, use timestamp-based sliding window
+        per_second_limit = RATE_LIMITS[@api_type][:per_second]
+        if per_second_limit && per_second_limit != Float::INFINITY
+          now = Time.now
+          # Remove requests older than 1 second
+          @request_times.reject! { |t| now - t >= 1.0 }
+
+          # Check if we've hit the per-second limit
+          if @request_times.size >= per_second_limit
+            # Calculate how long to wait until the oldest request is 1 second old
+            oldest_time = @request_times.min
+            wait_time = 1.0 - (now - oldest_time)
+
+            if wait_time.positive?
+              sleep(wait_time)
+              # Recalculate after sleep
+              now = Time.now
+              @request_times.reject! { |t| now - t >= 1.0 }
+            end
+          end
 
-      loop do
-        break if allow_request?
+          # Record this request time
+          @request_times << Time.now
+        end
 
-        sleep(0.1)
+        # Check other limits (per_minute, per_hour, per_day)
+        loop do
+          break if allow_request?
+
+          sleep(0.1)
+        end
+        record_request
       end
-      record_request
     end
 
     private
 
+    # Gets or creates a mutex for this API type for thread-safe throttling
+    def mutex
+      self.class.mutexes[@api_type] ||= Mutex.new
+    end
+
     # Prepares the counters used for each interval in {RATE_LIMITS}.
     def initialize_buckets
       RATE_LIMITS[@api_type].each_key do |interval|
+        # Skip per_second as we handle it with timestamps
+        next if interval == :per_second
+
         @buckets[interval] = Concurrent::AtomicFixnum.new(0)
       end
     end
@@ -67,6 +121,9 @@ module DhanHQ
     # @return [Boolean]
     def allow_request?
       RATE_LIMITS[@api_type].all? do |interval, limit|
+        # Skip per_second check as it's handled in throttle! with timestamps
+        next true if interval == :per_second
+
         @buckets[interval].value < limit
       end
     end
@@ -74,34 +131,32 @@ module DhanHQ
     # Increments the counters for each time window once a request is made.
     def record_request
       RATE_LIMITS[@api_type].each_key do |interval|
+        # Skip per_second as it's handled with timestamps
+        next if interval == :per_second
+
         @buckets[interval].increment
       end
     end
 
     # Spawns background threads to reset counters after each interval elapses.
     def start_cleanup_threads
-      Thread.new do
-        loop do
-          sleep(1)
-          @buckets[:per_second].value = 0
-        end
-      end
+      # Don't create per_second cleanup thread - we handle it with timestamps
       Thread.new do
         loop do
           sleep(60)
-          @buckets[:per_minute].value = 0
+          @buckets[:per_minute]&.value = 0
         end
       end
       Thread.new do
         loop do
           sleep(3600)
-          @buckets[:per_hour].value = 0
+          @buckets[:per_hour]&.value = 0
         end
       end
       Thread.new do
         loop do
           sleep(86_400)
-          @buckets[:per_day].value = 0
+          @buckets[:per_day]&.value = 0
         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.7"
+  VERSION = "2.1.10"
 end

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

@@ -213,7 +213,9 @@ module DhanHQ
 
           instrument = find_instrument(symbol_code, segment_hint)
           unless instrument
-            DhanHQ.logger&.warn("[DhanHQ::WS::MarketDepth] Unable to locate instrument for #{symbol_code} (segment hint: #{segment_hint || 'AUTO'})")
+            DhanHQ.logger&.warn(
+              "[DhanHQ::WS::MarketDepth] Unable to locate instrument for #{symbol_code} (segment hint: #{segment_hint || "AUTO"})"
+            )
             return nil
           end
 

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

@@ -184,8 +184,9 @@ module DhanHQ
 
         ##
         # Emit status-specific events
+        #
         # @param order_update [OrderUpdate] Current order update
-        # @param previous_state [OrderUpdate, nil] Previous order state
+        # @param _previous_state [OrderUpdate, nil] Previous order state (unused parameter)
         # rubocop:disable Metrics/MethodLength
         def emit_status_specific_events(order_update, _previous_state)
           case order_update.status

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

@@ -13,9 +13,6 @@ module DhanHQ
         # Initialize Orders WebSocket connection
         # @param url [String] WebSocket endpoint URL
         # @param options [Hash] Connection options
-        def initialize(url:, **options)
-          super
-        end
 
         private
 

data/lib/DhanHQ/ws/orders.rb

@@ -10,7 +10,8 @@ module DhanHQ
     module Orders
       ##
       # Connect to order updates WebSocket with a simple callback
-      # @param block [Proc] Callback for order updates
+      #
+      # @yield [OrderUpdate] Yields order update objects when received
       # @return [Client] WebSocket client instance
       def self.connect(&)
         Client.new.start.on(:update, &)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 2.1.7
+  version: 2.1.10
 platform: ruby
 authors:
 - Shubham Taywade