DhanHQ 2.4.0 → 2.6.0

data/lib/DhanHQ/models/position.rb

@@ -139,7 +139,7 @@ module DhanHQ
         #   puts "Total open position value: ₹#{total_value}"
         #
         def active
-          all.reject { |position| position.position_type == "CLOSED" }
+          all.reject { |position| position.position_type == DhanHQ::Constants::OrderStatus::CLOSED }
         end
 
         ##
@@ -205,6 +205,28 @@ module DhanHQ
           response = resource.convert(formatted_params)
           success_response?(response) ? response : DhanHQ::ErrorObject.new(response)
         end
+
+        ##
+        # Exits all active positions and cancels all open orders for the current trading day.
+        #
+        # This is a safety endpoint for emergency position closure. It sends a DELETE request
+        # to close all positions and cancel all pending orders in one call.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing operation result.
+        #   - **:status** [String] "SUCCESS" or "ERROR"
+        #   - **:message** [String] Description of the result
+        #
+        # @example Emergency exit all positions
+        #   response = DhanHQ::Models::Position.exit_all!
+        #   if response[:status] == "SUCCESS"
+        #     puts "✓ All positions exited and orders cancelled"
+        #   else
+        #     puts "✗ Failed: #{response[:message]}"
+        #   end
+        #
+        def exit_all!
+          resource.exit_all
+        end
       end
     end
   end

data/lib/DhanHQ/models/postback.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Utility model for parsing Dhan postback (webhook) payloads.
+    #
+    # Postback is a webhook mechanism where Dhan pushes order status updates to your
+    # configured URL. This model provides a convenient way to parse the incoming JSON
+    # payload into a typed, attribute-accessible object.
+    #
+    # @note Postback URL is configured in the Dhan web console when generating an access
+    #   token. It will NOT work with localhost or 127.0.0.1.
+    #
+    # @example Parse postback payload in a Rails controller
+    #   class DhanWebhooksController < ApplicationController
+    #     skip_before_action :verify_authenticity_token
+    #
+    #     def create
+    #       postback = DhanHQ::Models::Postback.parse(request.body.read)
+    #       case postback.order_status
+    #       when "TRADED"
+    #         handle_fill(postback)
+    #       when "REJECTED"
+    #         handle_rejection(postback)
+    #       end
+    #       head :ok
+    #     end
+    #   end
+    #
+    # @example Parse postback payload from a hash
+    #   postback = DhanHQ::Models::Postback.parse(params)
+    #   puts "Order #{postback.order_id} is now #{postback.order_status}"
+    #   puts "Filled: #{postback.filled_qty}/#{postback.quantity}"
+    #
+    class Postback < BaseModel
+      HTTP_PATH = nil # No API endpoint — postback is pushed to the user
+
+      attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
+                 :transaction_type, :exchange_segment, :product_type, :order_type,
+                 :validity, :trading_symbol, :security_id, :quantity,
+                 :disclosed_quantity, :price, :trigger_price, :after_market_order,
+                 :bo_profit_value, :bo_stop_loss_value, :leg_name,
+                 :create_time, :update_time, :exchange_time,
+                 :drv_expiry_date, :drv_option_type, :drv_strike_price,
+                 :oms_error_code, :oms_error_description, :filled_qty, :algo_id
+
+      class << self
+        ##
+        # Parse a postback webhook payload into a Postback model instance.
+        #
+        # Accepts either a JSON string (from request body) or a Hash (from parsed params).
+        # Keys are normalized to snake_case automatically.
+        #
+        # @param payload [String, Hash] Raw JSON string or Hash from the webhook
+        #
+        # @return [Postback] Parsed Postback object with typed attributes
+        #
+        # @example From raw JSON string
+        #   postback = DhanHQ::Models::Postback.parse('{"orderId":"123","orderStatus":"TRADED"}')
+        #   puts postback.order_status # => "TRADED"
+        #
+        # @example From a hash
+        #   postback = DhanHQ::Models::Postback.parse(order_id: "123", order_status: "TRADED")
+        #   puts postback.order_id # => "123"
+        #
+        def parse(payload)
+          data = case payload
+                 when String
+                   JSON.parse(payload)
+                 when Hash
+                   payload
+                 else
+                   raise ArgumentError, "Expected String or Hash, got #{payload.class}"
+                 end
+
+          new(data, skip_validation: true)
+        end
+      end
+
+      ##
+      # Whether the order has been fully traded.
+      #
+      # @return [Boolean]
+      def traded?
+        order_status == DhanHQ::Constants::OrderStatus::TRADED
+      end
+
+      ##
+      # Whether the order was rejected.
+      #
+      # @return [Boolean]
+      def rejected?
+        order_status == DhanHQ::Constants::OrderStatus::REJECTED
+      end
+
+      ##
+      # Whether the order is still pending.
+      #
+      # @return [Boolean]
+      def pending?
+        order_status == DhanHQ::Constants::OrderStatus::PENDING
+      end
+
+      ##
+      # Whether the order was cancelled.
+      #
+      # @return [Boolean]
+      def cancelled?
+        order_status == DhanHQ::Constants::OrderStatus::CANCELLED
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/profile.rb

@@ -125,16 +125,6 @@ module DhanHQ
 
       ##
       # Profile responses are informational and not validated locally.
-      #
-      # Since profile data is read-only account metadata, no validation contract
-      # is needed. The API response is trusted as-is.
-      #
-      # @return [nil] Always returns nil as profiles are read-only and informational
-      #
-      # @api private
-      def validation_contract
-        nil
-      end
     end
   end
 end

data/lib/DhanHQ/models/super_order.rb

@@ -48,6 +48,8 @@ module DhanHQ
     #   order.cancel("STOP_LOSS_LEG")
     #
     class SuperOrder < BaseModel
+      include Concerns::ApiResponseHandler
+
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
                  :transaction_type, :exchange_segment, :product_type, :order_type,
                  :validity, :trading_symbol, :security_id, :quantity,
@@ -284,8 +286,12 @@ module DhanHQ
       def modify(new_params)
         raise "Order ID is required to modify a super order" unless id
 
+        DhanHQ.logger&.info("[DhanHQ::Models::SuperOrder] Modifying super order #{id}")
         response = self.class.resource.update(id, new_params)
-        response["orderId"] == id
+        return false unless response.is_a?(Hash) && response["orderId"] == id
+
+        DhanHQ.logger&.info("[DhanHQ::Models::SuperOrder] Super order #{id} modified successfully")
+        true
       end
 
       ##
@@ -318,11 +324,15 @@ module DhanHQ
       #   order.cancel("TARGET_LEG")
       #
       # @raise [RuntimeError] If order ID is missing
-      def cancel(leg_name = "ENTRY_LEG")
+      def cancel(leg_name = DhanHQ::Constants::LegName::ENTRY_LEG)
         raise "Order ID is required to cancel a super order" unless id
 
+        DhanHQ.logger&.info("[DhanHQ::Models::SuperOrder] Cancelling super order #{id} leg #{leg_name}")
         response = self.class.resource.cancel(id, leg_name)
-        response["orderStatus"] == "CANCELLED"
+        return false unless response.is_a?(Hash) && response["orderStatus"] == DhanHQ::Constants::OrderStatus::CANCELLED
+
+        DhanHQ.logger&.info("[DhanHQ::Models::SuperOrder] Super order #{id} leg #{leg_name} cancelled successfully")
+        true
       end
     end
   end

data/lib/DhanHQ/models/trade.rb

@@ -49,8 +49,8 @@ module DhanHQ
         # 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
+        def resource
+          @resource ||= DhanHQ::Resources::Trades.new
         end
 
         ##
@@ -107,10 +107,8 @@ module DhanHQ
         #   puts "P&L: ₹#{pnl}"
         #
         def today
-          response = tradebook_resource.all
-          return [] unless response.is_a?(Array)
-
-          response.map { |trade_data| new(trade_data, skip_validation: true) }
+          response = resource.all
+          parse_collection_response(response)
         end
 
         ##
@@ -145,7 +143,7 @@ module DhanHQ
             raise DhanHQ::ValidationError, "Invalid order_id: #{validation_result.errors.to_h}"
           end
 
-          response = tradebook_resource.find(order_id)
+          response = 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
@@ -248,16 +246,6 @@ module DhanHQ
         alias all history
       end
 
-      ##
-      # 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
-
       ##
       # Checks if the trade is a BUY transaction.
       #
@@ -270,7 +258,7 @@ module DhanHQ
       #   end
       #
       def buy?
-        transaction_type == "BUY"
+        transaction_type == DhanHQ::Constants::TransactionType::BUY
       end
 
       ##
@@ -285,7 +273,7 @@ module DhanHQ
       #   end
       #
       def sell?
-        transaction_type == "SELL"
+        transaction_type == DhanHQ::Constants::TransactionType::SELL
       end
 
       ##
@@ -299,7 +287,7 @@ module DhanHQ
       #   puts "Equity trades: #{equity_trades.count}"
       #
       def equity?
-        instrument == "EQUITY"
+        instrument == DhanHQ::Constants::InstrumentType::EQUITY
       end
 
       ##
@@ -327,7 +315,7 @@ module DhanHQ
       #   puts "Option trades: #{option_trades.count}"
       #
       def option?
-        %w[CALL PUT].include?(drv_option_type)
+        [DhanHQ::Constants::OptionType::CALL, DhanHQ::Constants::OptionType::PUT].include?(drv_option_type)
       end
 
       ##
@@ -341,7 +329,7 @@ module DhanHQ
       #   puts "Call option trades: #{call_trades.count}"
       #
       def call_option?
-        drv_option_type == "CALL"
+        drv_option_type == DhanHQ::Constants::OptionType::CALL
       end
 
       ##
@@ -355,7 +343,7 @@ module DhanHQ
       #   puts "Put option trades: #{put_trades.count}"
       #
       def put_option?
-        drv_option_type == "PUT"
+        drv_option_type == DhanHQ::Constants::OptionType::PUT
       end
 
       ##

data/lib/DhanHQ/resources/ip_setup.rb

@@ -2,7 +2,8 @@
 
 module DhanHQ
   module Resources
-    # Resource for IP whitelist per API docs: GET /ip/getIP, POST /ip/setIP, PUT /ip/modifyIP.
+    # Resource for IP whitelist per API docs: GET /v2/ip/getIP, POST /v2/ip/setIP, PUT /v2/ip/modifyIP.
+    # Set/Modify require dhanClientId, ip, ipFlag (PRIMARY | SECONDARY). See dhanhq.co/docs/v2/authentication/#setup-static-ip
     class IPSetup < BaseAPI
       API_TYPE  = :order_api
       HTTP_PATH = "/ip"
@@ -11,12 +12,22 @@ module DhanHQ
         get("/getIP")
       end
 
-      def set(ip:)
-        post("/setIP", params: { ip: ip })
+      # @param ip [String] Static IP (IPv4 or IPv6)
+      # @param ip_flag [String] "PRIMARY" or "SECONDARY"
+      # @param dhan_client_id [String, nil] Defaults to DhanHQ.configuration.client_id when nil
+      def set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)
+        params = { ip: ip, ip_flag: ip_flag }
+        params[:dhan_client_id] = dhan_client_id || DhanHQ.configuration&.client_id
+        post("/setIP", params: params)
       end
 
-      def update(ip:)
-        put("/modifyIP", params: { ip: ip })
+      # @param ip [String] Static IP (IPv4 or IPv6)
+      # @param ip_flag [String] "PRIMARY" or "SECONDARY"
+      # @param dhan_client_id [String, nil] Defaults to DhanHQ.configuration.client_id when nil
+      def update(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)
+        params = { ip: ip, ip_flag: ip_flag }
+        params[:dhan_client_id] = dhan_client_id || DhanHQ.configuration&.client_id
+        put("/modifyIP", params: params)
       end
     end
   end

data/lib/DhanHQ/resources/kill_switch.rb

@@ -1,20 +1,30 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module DhanHQ
   module Resources
     # Resource client to control the trading kill switch feature.
+    # API expects killSwitchStatus as query parameter (no body). See dhanhq.co/docs/v2/traders-control/
     class KillSwitch < BaseAPI
-      # Kill switch operations execute on the trading API tier.
-      API_TYPE = :order_api
-      # Base path for kill switch operations.
+      API_TYPE  = :order_api
       HTTP_PATH = "/v2/killswitch"
 
-      # Enables or disables the kill switch.
+      # Enables or disables the kill switch via query parameter (doc: no body).
       #
-      # @param params [Hash]
+      # @param status [String] "ACTIVATE" or "DEACTIVATE"
       # @return [Hash]
-      def update(params)
-        post("", params: params)
+      def update(status)
+        query = "?killSwitchStatus=#{CGI.escape(status.to_s)}"
+        handle_response(client.post(build_path(query), {}))
+      end
+
+      ##
+      # Fetches the current kill switch status.
+      #
+      # @return [Hash] API response containing dhan_client_id and kill_switch_status.
+      def status
+        get("")
       end
     end
   end

data/lib/DhanHQ/resources/margin_calculator.rb

@@ -17,6 +17,15 @@ module DhanHQ
       def calculate(params)
         post("", params: params)
       end
+
+      ##
+      # Calculate margin requirements for multiple scripts in one request.
+      #
+      # @param params [Hash] Request parameters including scripList, includePosition, includeOrder.
+      # @return [Hash] API response containing combined margin details with hedge benefit.
+      def calculate_multi(params)
+        post("/multi", params: params)
+      end
     end
   end
 end

data/lib/DhanHQ/resources/orders.rb

@@ -1,70 +1,70 @@
 # frozen_string_literal: true
 
 module DhanHQ
-  # REST API wrappers grouped by resource type.
   module Resources
-    # Resource client for managing equity and F&O orders.
+    # Handles order placement, modification, and cancellation
     class Orders < BaseAPI
-      # Orders are routed through the trading API tier.
       API_TYPE = :order_api
-      # Base path for order endpoints.
       HTTP_PATH = "/v2/orders"
 
-      # Retrieve all orders for the current trading day.
-      #
-      # @return [Array<Hash>]
-      def all
-        get("")
-      end
+      # --------------------------------------------------
+      # PUBLIC API
+      # --------------------------------------------------
 
-      # Places a new order using the provided payload.
-      #
-      # @param params [Hash]
-      # @return [Hash]
       def create(params)
+        validate_place_order!(params)
         post("", params: params)
       end
 
-      # Fetches a single order by broker order id.
-      #
-      # @param order_id [String]
-      # @return [Hash]
-      def find(order_id)
-        get("/#{order_id}")
-      end
-
-      # Modifies an existing order.
-      #
-      # @param order_id [String]
-      # @param params [Hash]
-      # @return [Hash]
       def update(order_id, params)
+        validate_modify_order!(params.merge(order_id: order_id))
         put("/#{order_id}", params: params)
       end
 
-      # Cancels an existing order.
-      #
-      # @param order_id [String]
-      # @return [Hash]
+      def slicing(params)
+        validate_place_order!(params)
+        post("/slicing", params: params)
+      end
+
       def cancel(order_id)
         delete("/#{order_id}")
       end
 
-      # Places a slicing order request.
-      #
-      # @param params [Hash]
-      # @return [Hash]
-      def slicing(params)
-        post("/slicing", params: params)
+      def all
+        get("")
+      end
+
+      def find(order_id)
+        get("/#{order_id}")
       end
 
-      # Retrieve an order by client-supplied correlation id.
-      #
-      # @param correlation_id [String]
-      # @return [Hash]
       def by_correlation(correlation_id)
         get("/external/#{correlation_id}")
       end
+
+      # --------------------------------------------------
+      # VALIDATION LAYER
+      # --------------------------------------------------
+
+      private
+
+      def validate_place_order!(params)
+        result = Contracts::PlaceOrderContract.new.call(normalize_keys_for_validation(params))
+        raise_validation_error!(result) unless result.success?
+      end
+
+      def validate_modify_order!(params)
+        result = Contracts::ModifyOrderContract.new.call(normalize_keys_for_validation(params))
+        raise_validation_error!(result) unless result.success?
+      end
+
+      def normalize_keys_for_validation(params)
+        snake_case(params)
+      end
+
+      def raise_validation_error!(result)
+        raise DhanHQ::Error, "Validation Error: #{result.errors.to_h}"
+      end
     end
   end
 end

data/lib/DhanHQ/resources/pnl_exit.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource for P&L Based Exit endpoints per https://dhanhq.co/docs/v2/traders-control/
+    # POST /v2/pnlExit — configure, DELETE /v2/pnlExit — stop, GET /v2/pnlExit — status.
+    class PnlExit < BaseAPI
+      API_TYPE  = :order_api
+      HTTP_PATH = "/v2/pnlExit"
+
+      ##
+      # Configure automatic P&L-based position exit.
+      #
+      # @param params [Hash] Request body with profitValue, lossValue, productType, enableKillSwitch.
+      # @return [Hash] API response containing pnlExitStatus and message.
+      def configure(params)
+        post("", params: params)
+      end
+
+      ##
+      # Stop/disable the active P&L-based exit configuration.
+      #
+      # @return [Hash] API response containing pnlExitStatus and message.
+      def stop
+        delete("")
+      end
+
+      ##
+      # Fetch the currently active P&L-based exit configuration.
+      #
+      # @return [Hash] API response containing pnlExitStatus, profit, loss, segments, enable_kill_switch.
+      def status
+        get("")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/positions.rb

@@ -24,6 +24,14 @@ module DhanHQ
       def convert(params)
         post("/convert", params: params)
       end
+
+      ##
+      # Exit all active positions and cancel all open orders.
+      #
+      # @return [Hash] API response containing status and message.
+      def exit_all
+        delete("")
+      end
     end
   end
 end

data/lib/DhanHQ/version.rb

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

data/lib/DhanHQ/ws/cmd_bus.rb

@@ -6,7 +6,7 @@ module DhanHQ
     # connection is ready to send them.
     class CmdBus
       # Represents a subscription command queued for execution.
-      Command = Struct.new(:op, :payload, keyword_init: true)
+      Command = Struct.new(:op, :payload)
 
       def initialize
         @q = Queue.new

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

@@ -201,17 +201,17 @@ module DhanHQ
         # @param _previous_state [OrderUpdate, nil] Previous order state (unused parameter)
         def emit_status_specific_events(order_update, _previous_state)
           case order_update.status
-          when "TRANSIT"
+          when DhanHQ::Constants::OrderStatus::TRANSIT
             emit(:order_transit, order_update)
-          when "PENDING"
+          when DhanHQ::Constants::OrderStatus::PENDING
             emit(:order_pending, order_update)
-          when "REJECTED"
+          when DhanHQ::Constants::OrderStatus::REJECTED
             emit(:order_rejected, order_update)
-          when "CANCELLED"
+          when DhanHQ::Constants::OrderStatus::CANCELLED
             emit(:order_cancelled, order_update)
-          when "TRADED"
+          when DhanHQ::Constants::OrderStatus::TRADED
             emit(:order_traded, order_update)
-          when "EXPIRED"
+          when DhanHQ::Constants::OrderStatus::EXPIRED
             emit(:order_expired, order_update)
           end
         end

data/lib/DhanHQ/ws/singleton_lock.rb

@@ -14,7 +14,8 @@ module DhanHQ
         key = Digest::SHA256.hexdigest("#{client_id}:#{token}")[0, 12]
         @path = File.expand_path("tmp/dhanhq_ws_#{key}.lock", Dir.pwd)
         FileUtils.mkdir_p(File.dirname(@path))
-        @fh = File.open(@path, File::RDWR | File::CREAT, 0o644)
+        # Lock file must stay open until release!; block form would close it and release the lock.
+        @fh = File.open(@path, File::RDWR | File::CREAT, 0o644) # rubocop:disable Style/FileOpen
       end
 
       # Attempts to acquire the lock for the current process.

data/lib/dhanhq/analysis/options_buying_advisor.rb

@@ -91,7 +91,7 @@ module DhanHQ
 
         # Use OptionChain model: pick nearest/next expiry and fetch chain
         sid = @data.dig(:meta, :security_id)
-        seg = @data.dig(:meta, :exchange_segment) || "IDX_I"
+        seg = @data.dig(:meta, :exchange_segment) || DhanHQ::Constants::ExchangeSegment::IDX_I
         return unless sid && seg
 
         expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(underlying_scrip: sid.to_i, underlying_seg: seg)
@@ -128,7 +128,7 @@ module DhanHQ
       end
 
       def index_instrument?(meta)
-        meta[:instrument].to_s == "INDEX" || meta[:exchange_segment].to_s == "IDX_I"
+        meta[:instrument].to_s == DhanHQ::Constants::InstrumentType::INDEX || meta[:exchange_segment].to_s == DhanHQ::Constants::ExchangeSegment::IDX_I
       end
 
       def select_strike(side:, moneyness:)