DhanHQ 3.1.0 → 3.2.0

data/lib/DhanHQ/models/global_stocks/order_estimate.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    module GlobalStocks
+      ##
+      # Charge estimate for a prospective Global Stocks order.
+      #
+      # @example Estimate the cost of a trade before placing it
+      #   est = DhanHQ::Models::GlobalStocks::OrderEstimate.calculate(
+      #     security_id: "AAPL", transaction_type: "BUY", price: 180.0, quantity: 1
+      #   )
+      #   puts "Charges: $#{est.total_charges}"
+      #
+      class OrderEstimate < BaseModel
+        HTTP_PATH = "/v2/globalstocks/transEstimate"
+
+        attributes :brokerage, :order_charges, :exchange_charges, :turn_over_fee,
+                   :gst_charges, :other_charges
+
+        # Returns a concise prompt-friendly summary of the charges.
+        def to_prompt
+          parts = []
+          parts << "brokerage=$#{brokerage}" if brokerage
+          parts << "exchange=$#{exchange_charges}" if exchange_charges
+          parts << "gst=$#{gst_charges}" if gst_charges
+          parts << "total=$#{total_charges}"
+          parts.join(", ")
+        end
+
+        # Sum of every charge component.
+        #
+        # The API also returns +order_charges+ as its own total; this method adds up
+        # the components so the figure stays correct even when the API omits it.
+        #
+        # @return [Float]
+        def total_charges
+          [brokerage, exchange_charges, turn_over_fee, gst_charges, other_charges]
+            .sum(&:to_f)
+            .round(4)
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::MarginCalculator]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::MarginCalculator.new
+          end
+
+          # Estimates the charges applicable to a Global Stocks order.
+          #
+          # @param params [Hash] `:security_id`, `:transaction_type`, `:price`, `:quantity`
+          # @return [OrderEstimate]
+          def calculate(params)
+            new(resource.estimate(params), skip_validation: true)
+          end
+          alias estimate calculate
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/global_stocks/trade.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    module GlobalStocks
+      ##
+      # A single executed Global Stocks (US equity) trade.
+      #
+      # @example Today's US trades
+      #   DhanHQ::Models::GlobalStocks::Trade.all.each do |t|
+      #     puts "#{t.trading_symbol} #{t.traded_quantity} @ $#{t.traded_price}"
+      #   end
+      #
+      # @example Trades for one symbol
+      #   DhanHQ::Models::GlobalStocks::Trade.find_by_security_id("AAPL")
+      #
+      class Trade < BaseModel
+        HTTP_PATH = "/v2/globalstocks/trades"
+
+        attributes :dhan_client_id, :order_id, :exchange_order_id, :transaction_type,
+                   :exchange_segment, :product_type, :order_type, :trading_symbol,
+                   :security_id, :traded_quantity, :traded_price, :trade_date,
+                   :create_time, :exchange_time, :order_status, :brokerage,
+                   :other_charges, :trade_value
+
+        # Returns a concise prompt-friendly summary of the trade.
+        def to_prompt
+          parts = ["#{transaction_type} #{traded_quantity}x #{trading_symbol || security_id}"]
+          parts << "@ $#{traded_price}" if traded_price
+          parts << "value=$#{trade_value}" if trade_value
+          parts << "on #{trade_date}" if trade_date
+          parts.join(", ")
+        end
+
+        # Total cost of the trade, brokerage and other charges combined.
+        #
+        # @return [Float]
+        def total_charges
+          brokerage.to_f + other_charges.to_f
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::Trades]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::Trades.new
+          end
+
+          # Retrieves the current trading day's executed Global Stocks trades.
+          #
+          # @return [Array<Trade>]
+          def all
+            build_collection(resource.all)
+          end
+
+          # Retrieves executed Global Stocks trades for a single security.
+          #
+          # @param security_id [String]
+          # @return [Array<Trade>]
+          def find_by_security_id(security_id)
+            build_collection(resource.by_security_id(security_id))
+          end
+
+          private
+
+          def build_collection(response)
+            return [] unless response.is_a?(Array)
+
+            response.map { |trade| new(trade, skip_validation: true) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/margin.rb

@@ -142,7 +142,11 @@ module DhanHQ
         #   puts "Total margin: #{margin.total_margin}"
         #
         def calculate_multi(params)
-          # Map scripts to scrip_list and include_orders to include_order if provided
+          # Work on a copy: callers may pass a frozen or reused hash, and normalising
+          # their argument in place is a side effect they cannot see from the signature.
+          params = params.dup
+
+          # Accept either spelling of the collection and order flags.
           params[:scrip_list] ||= params[:scripts] if params.key?(:scripts)
           params[:include_order] ||= params[:include_orders] if params.key?(:include_orders)
           params[:dhan_client_id] ||= DhanHQ.configuration.client_id

data/lib/DhanHQ/models/multi_order.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # A basket of up to 15 orders placed in a single request via
+    # POST /v2/alerts/multi/orders.
+    #
+    # Unlike {AlertOrder} there is no trigger condition — every leg goes to the
+    # exchange immediately. The API answers with one result per leg, keyed by the
+    # +sequence+ you supplied, so partial acceptance is visible.
+    #
+    # @example Place a two-leg basket
+    #   result = DhanHQ::Models::MultiOrder.place([
+    #     { sequence: "1", transaction_type: "BUY", exchange_segment: "NSE_EQ",
+    #       product_type: "CNC", order_type: "LIMIT", validity: "DAY",
+    #       security_id: "11536", quantity: 1, price: 1500.0 },
+    #     { sequence: "2", transaction_type: "BUY", exchange_segment: "NSE_EQ",
+    #       product_type: "CNC", order_type: "MARKET", validity: "DAY",
+    #       security_id: "1333", quantity: 2 }
+    #   ])
+    #
+    #   result.all_accepted?          # => true
+    #   result.rejected               # => []
+    #   result.order_ids              # => ["112111182198", "112111182199"]
+    #   result.for_sequence("1").order_id
+    #
+    class MultiOrder < BaseModel
+      HTTP_PATH = "/v2/alerts/multi/orders"
+
+      attributes :orders
+
+      ##
+      # One leg's result within a {MultiOrder} response.
+      class Leg < BaseModel
+        attributes :order_id, :sequence, :order_status
+
+        # @return [Boolean] True when the exchange accepted this leg.
+        def accepted?
+          !order_id.nil? && !rejected?
+        end
+
+        # @return [Boolean] True when this leg was rejected.
+        def rejected?
+          order_status.to_s == DhanHQ::Constants::OrderStatus::REJECTED
+        end
+
+        # Returns a concise prompt-friendly summary of the leg.
+        def to_prompt
+          "seq=#{sequence} order_id=#{order_id} status=#{order_status}"
+        end
+      end
+
+      # Per-leg results.
+      #
+      # @return [Array<Leg>]
+      def legs
+        @legs ||= Array(orders).map { |leg| Leg.new(leg, skip_validation: true) }
+      end
+
+      # Order ids of every leg the API returned one for.
+      #
+      # @return [Array<String>]
+      def order_ids
+        legs.filter_map(&:order_id)
+      end
+
+      # Legs the exchange accepted.
+      #
+      # @return [Array<Leg>]
+      def accepted
+        legs.select(&:accepted?)
+      end
+
+      # Legs the exchange rejected.
+      #
+      # @return [Array<Leg>]
+      def rejected
+        legs.reject(&:accepted?)
+      end
+
+      # @return [Boolean] True when every leg was accepted.
+      def all_accepted?
+        legs.any? && rejected.empty?
+      end
+
+      # @return [Boolean] True when some but not all legs were accepted.
+      def partially_accepted?
+        accepted.any? && rejected.any?
+      end
+
+      # Looks up a leg by the sequence supplied at placement.
+      #
+      # @param sequence [String, Integer]
+      # @return [Leg, nil]
+      def for_sequence(sequence)
+        legs.find { |leg| leg.sequence.to_s == sequence.to_s }
+      end
+
+      # Returns a concise prompt-friendly summary of the basket.
+      def to_prompt
+        "#{legs.size} legs, #{accepted.size} accepted, #{rejected.size} rejected"
+      end
+
+      class << self
+        # @return [DhanHQ::Resources::MultiOrders]
+        def resource
+          @resource ||= DhanHQ::Resources::MultiOrders.new
+        end
+
+        # Places a basket of orders.
+        #
+        # @param orders [Array<Hash>] Order legs. See {DhanHQ::Contracts::MultiOrderContract}.
+        # @param dhan_client_id [String, nil] Defaults to the configured client id.
+        # @return [MultiOrder, DhanHQ::ErrorObject]
+        def place(orders, dhan_client_id: nil)
+          DhanHQ.logger&.info("[#{name}] Placing multi order with #{Array(orders).size} legs")
+          response = resource.create(orders, dhan_client_id: dhan_client_id)
+
+          # The API may answer with a bare array of leg results or wrap it in `orders`.
+          payload = response.is_a?(Array) ? { orders: response } : response
+          return DhanHQ::ErrorObject.new(response) unless payload.is_a?(Hash) && payload[:orders]
+
+          new(payload, skip_validation: true)
+        end
+        alias create place
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/funds.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks fund limit.
+      #
+      #   GET /v2/globalstocks/fundlimit
+      #
+      # Global Stocks funds are held in USD and are reported separately from the
+      # domestic INR fund limit exposed by {DhanHQ::Resources::Funds}.
+      class Funds < BaseAPI
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/fundlimit"
+
+        # Retrieves the authenticated user's US stock fund limit details.
+        #
+        # @return [Hash]
+        def fetch
+          get("")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/holdings.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for Global Stocks holdings.
+      #
+      #   GET /v2/globalstocks/holdings
+      class Holdings < BaseAPI
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/holdings"
+
+        # Retrieves the authenticated user's US stock holdings.
+        #
+        # @return [Array<Hash>]
+        def all
+          get("")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/margin_calculator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks pre-trade calculators.
+      #
+      #   POST /v2/globalstocks/margincalculator  — margin required for an order
+      #   POST /v2/globalstocks/transEstimate     — charges applicable to an order
+      #
+      # Both endpoints take the same request body. The API documents +price+ and
+      # +quantity+ as strings, so numeric input is stringified before sending.
+      class MarginCalculator < BaseAPI
+        API_TYPE = :non_trading_api
+        HTTP_PATH = "/v2/globalstocks"
+
+        # Calculates the margin required for a Global Stocks order.
+        #
+        # @param params [Hash] `:security_id`, `:transaction_type`, `:price`, `:quantity`
+        # @return [Hash] Margin breakdown.
+        def calculate(params)
+          post("/margincalculator", params: wire_params(params))
+        end
+
+        # Estimates the charges applicable to a Global Stocks order.
+        #
+        # @param params [Hash] `:security_id`, `:transaction_type`, `:price`, `:quantity`
+        # @return [Hash] Charge breakdown.
+        def estimate(params)
+          post("/transEstimate", params: wire_params(params))
+        end
+
+        private
+
+        # Validates against the shared estimator contract, then renders the numeric
+        # fields as strings the way the API expects them.
+        def wire_params(params)
+          validated = validate!(params)
+          validated.merge(
+            price: format_number(validated[:price]),
+            quantity: format_number(validated[:quantity])
+          )
+        end
+
+        # Fields the API documents as strings but which are validated as numbers.
+        NUMERIC_KEYS = %i[price quantity].freeze
+        private_constant :NUMERIC_KEYS
+
+        def validate!(params)
+          attrs = snake_case(params).each_with_object({}) do |(key, value), out|
+            out[key] = NUMERIC_KEYS.include?(key) ? Float(value) : value
+          end
+          result = Contracts::GlobalStocksEstimatorContract.new.call(attrs)
+          raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}" unless result.success?
+
+          result.to_h
+        rescue ArgumentError, TypeError => e
+          raise DhanHQ::ValidationError, "Invalid parameters: price and quantity must be numeric (#{e.message})"
+        end
+
+        # Renders 180.0 as "180" and 1.5 as "1.5" so the payload matches the
+        # documented examples rather than leaking Ruby float formatting.
+        def format_number(value)
+          float = Float(value)
+          float == float.to_i ? float.to_i.to_s : float.to_s
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/market_status.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the US market session status.
+      #
+      #   GET /v2/globalstocks/marketstatus
+      class MarketStatus < BaseAPI
+        API_TYPE = :non_trading_api
+        HTTP_PATH = "/v2/globalstocks/marketstatus"
+
+        # Retrieves the current US market status and session timings.
+        #
+        # @return [Hash] `{ status:, marketOpenTime:, marketCloseTime:, holidayFlag: }`
+        def fetch
+          get("")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/orders.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "../../concerns/order_audit"
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks (US equities) order endpoints.
+      #
+      #   POST   /v2/globalstocks/orders
+      #   PUT    /v2/globalstocks/orders/{order-id}
+      #   DELETE /v2/globalstocks/orders/{order-id}
+      #   GET    /v2/globalstocks/orders
+      #   GET    /v2/globalstocks/orders/{order-id}
+      #
+      # Writes go through the same {DhanHQ::Concerns::OrderAudit} guardrails as
+      # domestic orders: +ENV["LIVE_TRADING"]="true"+ is required, and every attempt
+      # emits a structured audit log line.
+      #
+      # The pre-trade {DhanHQ::Risk::Pipeline} is intentionally *not* run here. Its
+      # checks (lot-size multiples, ASM/GSM surveillance lists, F&O product support,
+      # NSE/BSE market hours) resolve instruments from the Indian scrip master, which
+      # does not contain US securities.
+      #
+      # @see https://dhanhq.co/docs/v2/ Global Stocks section
+      class Orders < BaseAPI
+        include DhanHQ::Concerns::OrderAudit
+
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/orders"
+
+        # Places a new Global Stocks order.
+        #
+        # @param params [Hash] Order attributes in snake_case. See
+        #   {DhanHQ::Contracts::GlobalStocksPlaceOrderContract} for the accepted keys.
+        # @return [Hash] `{ orderId:, orderStatus: }`
+        # @raise [DhanHQ::LiveTradingDisabledError] Unless LIVE_TRADING is enabled.
+        # @raise [DhanHQ::ValidationError] When the payload fails validation.
+        def create(params)
+          ensure_live_trading!
+          log_order_context("DHAN_GLOBAL_ORDER_ATTEMPT", params)
+          validate_place_order!(params)
+          post("", params: params)
+        end
+
+        # Modifies a pending Global Stocks order.
+        #
+        # @param order_id [String]
+        # @param params [Hash] Fields to change, in snake_case.
+        # @return [Hash] `{ orderId:, orderStatus: }`
+        def update(order_id, params)
+          ensure_live_trading!
+          log_order_context("DHAN_GLOBAL_ORDER_MODIFY_ATTEMPT", params.merge(order_id: order_id))
+          validate_modify_order!(params.merge(order_id: order_id))
+          put("/#{order_id}", params: params)
+        end
+
+        # Cancels a pending Global Stocks order.
+        #
+        # @param order_id [String]
+        # @return [Hash] `{ orderId:, orderStatus: }`
+        def cancel(order_id)
+          ensure_live_trading!
+          log_order_context("DHAN_GLOBAL_ORDER_CANCEL_ATTEMPT", { order_id: order_id })
+          delete("/#{order_id}")
+        end
+
+        # Retrieves the current trading day's Global Stocks order book.
+        #
+        # @return [Array<Hash>]
+        def all
+          get("")
+        end
+
+        # Retrieves a single Global Stocks order by its Dhan order id.
+        #
+        # @param order_id [String]
+        # @return [Hash]
+        def find(order_id)
+          get("/#{order_id}")
+        end
+
+        private
+
+        def validate_place_order!(params)
+          result = Contracts::GlobalStocksPlaceOrderContract.new.call(coerce_for_validation(params))
+          raise_validation_error!(result) unless result.success?
+        end
+
+        def validate_modify_order!(params)
+          result = Contracts::GlobalStocksModifyOrderContract.new.call(coerce_for_validation(params))
+          raise_validation_error!(result) unless result.success?
+        end
+
+        # Global Stocks quantities and prices are floats (fractional shares are
+        # supported), so integers handed in by callers are widened before validation.
+        def coerce_for_validation(params)
+          snake_case(params).each_with_object({}) do |(key, value), out|
+            out[key] = FLOAT_KEYS.include?(key) && value.is_a?(Integer) ? value.to_f : value
+          end
+        end
+
+        FLOAT_KEYS = %i[quantity price trigger_price stop_loss_price target_price amount].freeze
+        private_constant :FLOAT_KEYS
+
+        def raise_validation_error!(result)
+          raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/trades.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks trade book.
+      #
+      #   GET /v2/globalstocks/trades
+      #   GET /v2/globalstocks/trades/{security-id}
+      class Trades < BaseAPI
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/trades"
+
+        # Retrieves the current trading day's executed Global Stocks trades.
+        #
+        # @return [Array<Hash>]
+        def all
+          get("")
+        end
+
+        # Retrieves executed Global Stocks trades for a single security.
+        #
+        # @param security_id [String]
+        # @return [Array<Hash>]
+        def by_security_id(security_id)
+          get("/#{security_id}")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/multi_orders.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/order_audit"
+
+module DhanHQ
+  module Resources
+    # Resource for basket orders: POST /v2/alerts/multi/orders.
+    #
+    # Places up to {DhanHQ::Contracts::MultiOrderContract::MAX_ORDERS} unconditional
+    # orders in a single request. Unlike {AlertOrders} there is no trigger condition —
+    # every leg is sent to the exchange immediately.
+    #
+    # @see https://dhanhq.co/docs/v2/ Conditional and Multi Order section
+    class MultiOrders < BaseAPI
+      include DhanHQ::Concerns::OrderAudit
+
+      API_TYPE  = :order_api
+      HTTP_PATH = "/v2/alerts/multi/orders"
+
+      # Places a basket of orders.
+      #
+      # @param orders [Array<Hash>] Order legs in snake_case. Each leg requires
+      #   +:sequence+, +:transaction_type+ and +:exchange_segment+.
+      # @param dhan_client_id [String, nil] Defaults to the configured client id.
+      # @return [Hash] `{ orders: [{ orderId:, sequence:, orderStatus: }, ...] }`
+      # @raise [DhanHQ::LiveTradingDisabledError] Unless LIVE_TRADING is enabled.
+      # @raise [DhanHQ::ValidationError] When any leg fails validation.
+      def create(orders, dhan_client_id: nil)
+        ensure_live_trading!
+
+        legs = Array(orders).map { |leg| snake_case(leg) }
+        payload = { dhan_client_id: dhan_client_id || DhanHQ.configuration&.client_id, orders: legs }.compact
+
+        validate!(payload)
+        legs.each { |leg| run_risk_checks!(leg) }
+        log_multi_order_context(legs)
+
+        # BaseAPI camelizes only the top level, which would leave the leg fields as
+        # `transaction_type`/`security_id` inside `orders` and get the basket rejected.
+        post("", params: payload.merge(orders: deep_camelize_keys(legs)))
+      end
+
+      private
+
+      def validate!(payload)
+        result = Contracts::MultiOrderContract.new.call(payload)
+        raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}" unless result.success?
+      end
+
+      # Emits one audit line per leg so each order in the basket is traceable.
+      def log_multi_order_context(legs)
+        legs.each do |leg|
+          log_order_context("DHAN_MULTI_ORDER_ATTEMPT", leg)
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

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

data/lib/DhanHQ/write_paths.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Classifies request paths by whether they change account state.
+  #
+  # The distinction that matters on this API is **mutating vs read-only**, not GET vs
+  # POST: the option chain, market feed, historical charts and the margin calculators
+  # are all read-only POSTs. Both dry-run simulation and non-idempotent retry gating
+  # need that answer, so it lives here rather than in {DhanHQ::Client}.
+  module WritePaths
+    # HTTP methods that can change server-side state.
+    WRITE_METHODS = %i[post put patch delete].freeze
+
+    # Path of the basket order endpoint, which answers with one result per leg
+    # rather than a single order id.
+    MULTI_ORDER_PATH = "/v2/alerts/multi/orders"
+
+    module_function
+
+    # True when this request changes real account state.
+    #
+    # @param method [Symbol] HTTP method
+    # @param path [String, nil] Request path
+    # @return [Boolean]
+    def mutating?(method, path)
+      return false unless WRITE_METHODS.include?(method)
+
+      match?(path, DhanHQ::Constants::MUTATING_PATH_PREFIXES)
+    end
+
+    # True when this request places one or more orders.
+    #
+    # @param method [Symbol] HTTP method
+    # @param path [String, nil] Request path
+    # @return [Boolean]
+    def order_placement?(method, path)
+      return false unless method == :post
+
+      match?(path, DhanHQ::Constants::ORDER_PLACEMENT_PATH_PREFIXES)
+    end
+
+    # True for the basket order endpoint.
+    #
+    # @param path [String, nil] Request path
+    # @return [Boolean]
+    def multi_order?(path)
+      path.to_s.start_with?(MULTI_ORDER_PATH)
+    end
+
+    def match?(path, prefixes)
+      return false if path.nil?
+
+      prefixes.any? { |prefix| path.start_with?(prefix) }
+    end
+    private_class_method :match?
+  end
+end