DhanHQ 2.1.5 → 2.1.7

data/lib/DhanHQ/models/order_update.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Represents a real-time order update received via WebSocket
+    # Parses and provides access to all order update fields as per DhanHQ API documentation
+    # rubocop:disable Metrics/ClassLength
+    class OrderUpdate < BaseModel
+      # All order update attributes as per API documentation
+      attributes :exchange, :segment, :source, :security_id, :client_id,
+                 :exch_order_no, :order_no, :product, :txn_type, :order_type,
+                 :validity, :disc_quantity, :disc_qty_rem, :remaining_quantity,
+                 :quantity, :traded_qty, :price, :trigger_price, :traded_price,
+                 :avg_traded_price, :algo_ord_no, :off_mkt_flag, :order_date_time,
+                 :exch_order_time, :last_updated_time, :remarks, :mkt_type,
+                 :reason_description, :leg_no, :instrument, :symbol, :product_name,
+                 :status, :lot_size, :strike_price, :expiry_date, :opt_type,
+                 :display_name, :isin, :series, :good_till_days_date, :ref_ltp,
+                 :tick_size, :algo_id, :multiplier, :correlation_id
+
+      ##
+      # Create OrderUpdate from WebSocket message
+      # @param message [Hash] Raw WebSocket message
+      # @return [OrderUpdate] Parsed order update
+      def self.from_websocket_message(message)
+        return nil unless message.is_a?(Hash) && message[:Type] == "order_alert"
+        return nil unless message[:Data].is_a?(Hash)
+
+        # Map the WebSocket message data to our attributes
+        data = message[:Data]
+        new(data, skip_validation: true)
+      end
+
+      ##
+      # OrderUpdate objects are read-only, so no validation contract needed
+      def validation_contract
+        nil
+      end
+
+      ##
+      # Helper methods for transaction type
+      def buy?
+        txn_type == "B"
+      end
+
+      def sell?
+        txn_type == "S"
+      end
+
+      ##
+      # Helper methods for order type
+      def limit_order?
+        order_type == "LMT"
+      end
+
+      def market_order?
+        order_type == "MKT"
+      end
+
+      def stop_loss_order?
+        order_type == "SL"
+      end
+
+      def stop_loss_market_order?
+        order_type == "SLM"
+      end
+
+      ##
+      # Helper methods for product type
+      def cnc_product?
+        product == "C"
+      end
+
+      def intraday_product?
+        product == "I"
+      end
+
+      def margin_product?
+        product == "M"
+      end
+
+      def mtf_product?
+        product == "F"
+      end
+
+      def cover_order?
+        product == "V"
+      end
+
+      def bracket_order?
+        product == "B"
+      end
+
+      ##
+      # Helper methods for order status
+      def transit?
+        status == "TRANSIT"
+      end
+
+      def pending?
+        status == "PENDING"
+      end
+
+      def rejected?
+        status == "REJECTED"
+      end
+
+      def cancelled?
+        status == "CANCELLED"
+      end
+
+      def traded?
+        status == "TRADED"
+      end
+
+      def expired?
+        status == "EXPIRED"
+      end
+
+      ##
+      # Helper methods for instrument type
+      def equity?
+        instrument == "EQUITY"
+      end
+
+      def derivative?
+        instrument == "DERIVATIVES"
+      end
+
+      def option?
+        %w[CE PE].include?(opt_type)
+      end
+
+      def call_option?
+        opt_type == "CE"
+      end
+
+      def put_option?
+        opt_type == "PE"
+      end
+
+      ##
+      # Helper methods for order leg (for Super Orders)
+      def entry_leg?
+        leg_no == 1
+      end
+
+      def stop_loss_leg?
+        leg_no == 2
+      end
+
+      def target_leg?
+        leg_no == 3
+      end
+
+      ##
+      # Helper methods for market type
+      def normal_market?
+        mkt_type == "NL"
+      end
+
+      def auction_market?
+        %w[AU A1 A2].include?(mkt_type)
+      end
+
+      ##
+      # Helper methods for order characteristics
+      def amo_order?
+        off_mkt_flag == "1"
+      end
+
+      def super_order?
+        remarks == "Super Order"
+      end
+
+      def partially_executed?
+        traded_qty.positive? && traded_qty < quantity
+      end
+
+      def fully_executed?
+        traded_qty == quantity
+      end
+
+      def not_executed?
+        traded_qty.zero?
+      end
+
+      ##
+      # Calculation methods
+      def execution_percentage
+        return 0.0 if quantity.zero?
+
+        (traded_qty.to_f / quantity * 100).round(2)
+      end
+
+      def pending_quantity
+        quantity - traded_qty
+      end
+
+      def total_value
+        return 0 unless traded_qty && avg_traded_price
+
+        traded_qty * avg_traded_price
+      end
+
+      ##
+      # Status summary for logging/debugging
+      # rubocop:disable Metrics/MethodLength
+      def status_summary
+        {
+          order_no: order_no,
+          symbol: symbol,
+          status: status,
+          txn_type: txn_type,
+          quantity: quantity,
+          traded_qty: traded_qty,
+          execution_percentage: execution_percentage,
+          price: price,
+          avg_traded_price: avg_traded_price,
+          leg_no: leg_no,
+          super_order: super_order?
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      ##
+      # Convert to hash for serialization
+      def to_hash
+        @attributes.dup
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/DhanHQ/models/trade.rb

@@ -4,12 +4,14 @@ module DhanHQ
   module Models
     ##
     # Represents a single trade.
-    # The API docs show an array of trades from GET /v2/trades/{from-date}/{to-date}/{page}
+    # 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
     class Trade < BaseModel
-      # No explicit HTTP_PATH if we rely on the statements resource
-      # but we can define it if needed
       HTTP_PATH = "/v2/trades"
 
+      # All trade attributes as per API documentation
       attributes :dhan_client_id, :order_id, :exchange_order_id, :exchange_trade_id,
                  :transaction_type, :exchange_segment, :product_type, :order_type,
                  :trading_symbol, :custom_symbol, :security_id, :traded_quantity,
@@ -19,14 +21,6 @@ module DhanHQ
                  :drv_option_type, :drv_strike_price
 
       class << self
-        ##
-        # Provide a **shared instance** of the `Statements` resource,
-        # where we have `trade_history(from_date:, to_date:, page:)`.
-        # used for fetching historical trades.
-        def resource
-          @resource ||= DhanHQ::Resources::Statements.new
-        end
-
         ##
         # Resource for current day tradebook APIs
         def tradebook_resource
@@ -34,46 +28,139 @@ module DhanHQ
         end
 
         ##
-        # Fetch trades within the given date range and page.
-        # GET /v2/trades/{from-date}/{to-date}/{page}
-        #
-        # @param from_date [String]
-        # @param to_date   [String]
-        # @param page      [Integer] Default 0
-        # @return [Array<Trade>]
-        # Retrieve historical trades
-        def history(from_date:, to_date:, page: 0)
-          # The resource call returns an Array<Hash>.
-          response = resource.trade_history(from_date: from_date, to_date: to_date, page: page)
-          return [] unless response.is_a?(Array)
-
-          response.map { |t| new(t, skip_validation: true) }
+        # Resource for historical trade data
+        def statements_resource
+          @statements_resource ||= DhanHQ::Resources::Statements.new
         end
 
-        alias all history
-
-        # Retrieve current day trades
+        ##
+        # Fetch current day trades
+        # GET /v2/trades
+        #
+        # @return [Array<Trade>] Array of trades executed today
         def today
           response = tradebook_resource.all
           return [] unless response.is_a?(Array)
 
-          response.map { |t| new(t, skip_validation: true) }
+          response.map { |trade_data| new(trade_data, skip_validation: true) }
         end
 
-        # Fetch trades for a specific order id for the current day
+        ##
+        # Fetch trades for a specific order ID (current day)
+        # GET /v2/trades/{order-id}
+        #
+        # @param order_id [String] The order ID to fetch trades for
+        # @return [Trade, nil] Trade object or nil if not found
         def find_by_order_id(order_id)
+          # Validate input
+          contract = DhanHQ::Contracts::TradeByOrderIdContract.new
+          validation_result = contract.call(order_id: order_id)
+
+          unless validation_result.success?
+            raise DhanHQ::ValidationError, "Invalid order_id: #{validation_result.errors.to_h}"
+          end
+
           response = tradebook_resource.find(order_id)
           return nil unless response.is_a?(Hash) || (response.is_a?(Array) && response.any?)
 
           data = response.is_a?(Array) ? response.first : response
           new(data, skip_validation: true)
         end
+
+        ##
+        # Fetch historical trades within the given date range and page
+        # GET /v2/trades/{from-date}/{to-date}/{page}
+        #
+        # @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
+        def history(from_date:, to_date:, page: 0)
+          validate_history_params(from_date, to_date, page)
+
+          response = statements_resource.trade_history(
+            from_date: from_date,
+            to_date: to_date,
+            page: page
+          )
+
+          return [] unless response.is_a?(Array)
+
+          response.map { |trade_data| new(trade_data, skip_validation: true) }
+        end
+
+        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)
+
+          return if validation_result.success?
+
+          raise DhanHQ::ValidationError, "Invalid parameters: #{validation_result.errors.to_h}"
+        end
+
+        # Alias for backward compatibility
+        alias all history
       end
 
-      # If you want custom validations, you'd set a contract or skip for read-only
+      ##
+      # Trade objects are read-only, so no validation contract needed
       def validation_contract
         nil
       end
+
+      ##
+      # Helper methods for trade data
+      def buy?
+        transaction_type == "BUY"
+      end
+
+      def sell?
+        transaction_type == "SELL"
+      end
+
+      def equity?
+        instrument == "EQUITY"
+      end
+
+      def derivative?
+        instrument == "DERIVATIVES"
+      end
+
+      def option?
+        %w[CALL PUT].include?(drv_option_type)
+      end
+
+      def call_option?
+        drv_option_type == "CALL"
+      end
+
+      def put_option?
+        drv_option_type == "PUT"
+      end
+
+      ##
+      # Calculate total trade value
+      def total_value
+        return 0 unless traded_quantity && traded_price
+
+        traded_quantity * traded_price
+      end
+
+      ##
+      # Calculate total charges
+      def total_charges
+        charges = [sebi_tax, stt, brokerage_charges, service_tax,
+                   exchange_transaction_charges, stamp_duty].compact
+        charges.sum(&:to_f)
+      end
+
+      ##
+      # Net trade value after charges
+      def net_value
+        total_value - total_charges
+      end
     end
   end
 end

data/lib/DhanHQ/resources/expired_options_data.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    ##
+    # Resource for expired options data API endpoints
+    class ExpiredOptionsData < BaseAPI
+      API_TYPE = :data_api
+      HTTP_PATH = "/charts"
+
+      ##
+      # Fetch expired options data for rolling contracts
+      # POST /charts/rollingoption
+      #
+      # @param params [Hash] Parameters for the request
+      # @return [Hash] API response with expired options data
+      def fetch(params)
+        post("/rollingoption", params: params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

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

data/lib/DhanHQ/ws/base_connection.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "eventmachine"
+require "faye/websocket"
+require "json"
+require "concurrent"
+require "uri"
+
+module DhanHQ
+  module WS
+    ##
+    # Base WebSocket connection class providing common functionality
+    # for all DhanHQ WebSocket connections (Orders, Market Feed, Market Depth)
+    class BaseConnection
+      COOL_OFF_429 = 60  # seconds to cool off on 429
+      MAX_BACKOFF  = 90  # cap exponential backoff
+
+      attr_reader :stopping, :url, :callbacks, :started
+
+      ##
+      # Initialize base connection
+      # @param url [String] WebSocket endpoint URL
+      # @param options [Hash] Connection options
+      # @option options [Integer] :max_backoff Maximum backoff time (default: 90)
+      # @option options [Integer] :cool_off_429 Cool off time for 429 errors (default: 60)
+      def initialize(url:, **options)
+        @url = url
+        @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
+        @started = Concurrent::AtomicBoolean.new(false)
+        @stop = false
+        @stopping = false
+        @ws = nil
+        @timer = nil
+        @cooloff_until = nil
+        @thr = nil
+        @max_backoff = options[:max_backoff] || MAX_BACKOFF
+        @cool_off_429 = options[:cool_off_429] || COOL_OFF_429
+      end
+
+      ##
+      # Start the WebSocket connection
+      # @return [BaseConnection] self for method chaining
+      def start
+        return self if @started.true?
+
+        @started.make_true
+        @thr = Thread.new { loop_run }
+        self
+      end
+
+      ##
+      # Stop the WebSocket connection gracefully
+      # @return [BaseConnection] self for method chaining
+      def stop
+        return self unless @started.true?
+
+        @started.make_false
+        @stop = true
+        @stopping = true
+        @ws&.close
+        self
+      end
+
+      ##
+      # Force disconnect the WebSocket
+      # @return [BaseConnection] self for method chaining
+      def disconnect!
+        @stop = true
+        @stopping = true
+        @ws&.close
+        self
+      end
+
+      ##
+      # Check if connection is open
+      # @return [Boolean] true if connected
+      def open?
+        @ws && @ws.instance_variable_get(:@driver)&.ready_state == 1
+      rescue StandardError
+        false
+      end
+
+      ##
+      # Check if connection is connected (alias for open?)
+      # @return [Boolean] true if connected
+      def connected?
+        open?
+      end
+
+      ##
+      # Register event handler
+      # @param event [Symbol] Event type
+      # @param block [Proc] Event handler
+      # @return [BaseConnection] self for method chaining
+      def on(event, &block)
+        @callbacks[event] << block
+        self
+      end
+
+      ##
+      # Emit event to registered callbacks
+      # @param event [Symbol] Event type
+      # @param payload [Object] Event payload
+      def emit(event, payload = nil)
+        list = @callbacks[event] || []
+        list.each { |cb| cb.call(payload) }
+      rescue StandardError => e
+        DhanHQ.logger&.error("[DhanHQ::WS::BaseConnection] Error in event handler: #{e.class} #{e.message}")
+      end
+
+      ##
+      # Send message over WebSocket
+      # @param message [String, Hash] Message to send
+      def send_message(message)
+        return unless @ws && open?
+
+        data = message.is_a?(Hash) ? message.to_json : message
+        @ws.send(data)
+      rescue StandardError => e
+        DhanHQ.logger&.error("[DhanHQ::WS::BaseConnection] Error sending message: #{e.class} #{e.message}")
+      end
+
+      private
+
+      ##
+      # Main connection loop with reconnection logic
+      def loop_run
+        backoff = 2.0
+        until @stop
+          failed = false
+          got_429 = false
+
+          # Respect any active cool-off window
+          sleep (@cooloff_until - Time.now).ceil if @cooloff_until && Time.now < @cooloff_until
+
+          begin
+            failed, got_429 = run_session
+          rescue StandardError => e
+            DhanHQ.logger&.error("[DhanHQ::WS::BaseConnection] Connection 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::BaseConnection] Cooling off #{@cool_off_429}s due to 429")
+            end
+
+            if failed
+              sleep_time = [backoff, @max_backoff].min
+              jitter = rand(0.2 * sleep_time)
+              DhanHQ.logger&.warn("[DhanHQ::WS::BaseConnection] Reconnecting in #{(sleep_time + jitter).round(1)}s")
+              sleep(sleep_time + jitter)
+              backoff *= 2.0
+            else
+              backoff = 2.0
+            end
+          end
+        end
+      end
+
+      ##
+      # Run a single WebSocket session
+      # Must be implemented by subclasses
+      # @return [Array<Boolean>] [failed, got_429]
+      def run_session
+        raise NotImplementedError, "Subclasses must implement run_session"
+      end
+
+      ##
+      # Get default headers for WebSocket connection
+      # @return [Hash] Default headers
+      def default_headers
+        {
+          "User-Agent" => "DhanHQ-Ruby-Client/#{DhanHQ::VERSION}",
+          "Origin" => "https://dhanhq.co"
+        }
+      end
+
+      ##
+      # Sanitize URL for logging by removing sensitive parameters
+      # @param url [String] Original URL
+      # @return [String] Sanitized URL safe for logging
+      def sanitize_url(url)
+        return url if url.nil? || url.empty?
+
+        begin
+          uri = URI.parse(url)
+          # Remove sensitive query parameters
+          if uri.query
+            params = URI.decode_www_form(uri.query).reject do |key, _|
+              %w[token clientId client_id access_token].include?(key.downcase)
+            end
+            uri.query = URI.encode_www_form(params) unless params.empty?
+          end
+          uri.to_s
+        rescue StandardError
+          # If URL parsing fails, return a generic message
+          "wss://[sanitized-url]"
+        end
+      end
+
+      ##
+      # Handle WebSocket open event
+      def handle_open
+        DhanHQ.logger&.info("[DhanHQ::WS::BaseConnection] Connected to #{sanitize_url(@url)}")
+        emit(:open)
+        authenticate if respond_to?(:authenticate, true)
+      end
+
+      ##
+      # Handle WebSocket message event
+      # @param ev [Event] WebSocket message event
+      def handle_message(ev)
+        emit(:raw, ev.data)
+        process_message(ev.data) if respond_to?(:process_message, true)
+      end
+
+      ##
+      # Handle WebSocket close event
+      # @param ev [Event] WebSocket close event
+      def handle_close(ev)
+        @timer&.cancel
+        @timer = nil
+        msg = "[DhanHQ::WS::BaseConnection] Connection closed: #{ev.code} #{ev.reason}"
+        DhanHQ.logger&.warn(msg)
+
+        emit(:close, { code: ev.code, reason: ev.reason })
+
+        if @stopping
+          [false, false]
+        else
+          failed = (ev.code != 1000)
+          got_429 = ev.reason.to_s.include?("429")
+          [failed, got_429]
+        end
+      end
+
+      ##
+      # Handle WebSocket error event
+      # @param ev [Event] WebSocket error event
+      def handle_error(ev)
+        DhanHQ.logger&.error("[DhanHQ::WS::BaseConnection] WebSocket error: #{ev.message}")
+        emit(:error, ev.message)
+        [true, false]
+      end
+    end
+  end
+end