DhanHQ 2.1.8 → 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/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.1.10"
 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.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.8
+  version: 2.1.10
 platform: ruby
 authors:
 - Shubham Taywade