DhanHQ 3.1.0 → 3.2.0

data/lib/DhanHQ/dry_run/simulator.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "active_support/core_ext/hash/indifferent_access"
+
+module DhanHQ
+  module DryRun
+    # Answers state-changing requests locally instead of sending them.
+    #
+    # Reads still go to the API, so market data, the option chain, positions and
+    # holdings stay live and a strategy can be rehearsed against real prices. The one
+    # exception is a read for an order this simulator itself invented: those carry the
+    # {ID_PREFIX} sentinel, can only exist because of a dry run, and are replayed from
+    # the {Ledger} so the models' place-then-refetch flow completes without touching
+    # the network.
+    #
+    # Responses are shaped per endpoint family, because callers inspect them: order
+    # placements need an `orderId` for the models to treat the write as successful, and
+    # the basket endpoint needs an `orders` array or {DhanHQ::Models::MultiOrder} sees
+    # a failure.
+    class Simulator
+      # Marks an order id as fabricated by a dry run.
+      ID_PREFIX = "DRYRUN-"
+
+      # Extracts a fabricated id out of a request path.
+      ID_PATTERN = /#{Regexp.escape(ID_PREFIX)}[A-Za-z0-9]+/
+
+      def initialize(ledger: Ledger.instance)
+        @ledger = ledger
+      end
+
+      # Whether this request should be answered locally.
+      #
+      # @param method [Symbol] HTTP method
+      # @param path [String, nil] Request path
+      # @return [Boolean]
+      def simulates?(method, path)
+        return false unless DhanHQ.configuration&.dry_run?
+
+        WritePaths.mutating?(method, path) || replayable_read?(method, path)
+      end
+
+      # Builds — and logs — the response for a simulated request.
+      #
+      # @param method [Symbol] HTTP method
+      # @param path [String] Request path
+      # @param payload [Hash] The request body that will not be sent
+      # @return [ActiveSupport::HashWithIndifferentAccess]
+      def response_for(method, path, payload)
+        return replay(path) if replayable_read?(method, path)
+
+        log(method, path, payload)
+        body = simulated_body(method, path, payload)
+        body.merge("dryRun" => true, "method" => method.to_s.upcase, "path" => path)
+            .with_indifferent_access
+      end
+
+      private
+
+      # A GET for an id this simulator minted. Only reachable in dry run, so
+      # intercepting it never shadows a real read.
+      def replayable_read?(method, path)
+        method == :get && path.to_s.include?(ID_PREFIX)
+      end
+
+      def replay(path)
+        order_id = path.to_s[ID_PATTERN]
+        record = @ledger.fetch(order_id)
+        return record.with_indifferent_access if record
+
+        # Simulated in another process, or evicted from the ledger. Answer with the
+        # minimum a caller needs rather than falling through to a live request.
+        { "orderId" => order_id, "orderStatus" => DhanHQ::Constants::OrderStatus::TRANSIT, "dryRun" => true }
+          .with_indifferent_access
+      end
+
+      def simulated_body(method, path, payload)
+        if WritePaths.multi_order?(path)
+          simulated_basket(payload)
+        elsif WritePaths.order_placement?(method, path)
+          simulated_order(payload)
+        else
+          {}
+        end
+      end
+
+      # Echoes the submitted fields back alongside the fabricated id, so a model built
+      # from the ledger record looks like the order that would have been placed.
+      def simulated_order(payload)
+        order_id = generate_id
+        record = stringify(payload).merge(
+          "orderId" => order_id,
+          "orderStatus" => DhanHQ::Constants::OrderStatus::TRANSIT,
+          "dryRun" => true
+        )
+        @ledger.record(order_id, record)
+        { "orderId" => order_id, "orderStatus" => DhanHQ::Constants::OrderStatus::TRANSIT }
+      end
+
+      # One result per submitted leg, keyed by the caller's sequence, mirroring the
+      # real basket response.
+      def simulated_basket(payload)
+        legs = stringify(payload)["orders"]
+        legs = [] unless legs.is_a?(Array)
+
+        orders = legs.each_with_index.map do |leg, index|
+          order_id = generate_id
+          sequence = (leg.is_a?(Hash) ? leg["sequence"] : nil) || (index + 1).to_s
+          @ledger.record(order_id, (leg.is_a?(Hash) ? leg : {}).merge("orderId" => order_id, "dryRun" => true))
+          {
+            "orderId" => order_id,
+            "sequence" => sequence,
+            "orderStatus" => DhanHQ::Constants::OrderStatus::TRANSIT
+          }
+        end
+
+        { "orders" => orders }
+      end
+
+      def generate_id
+        "#{ID_PREFIX}#{SecureRandom.hex(6).upcase}"
+      end
+
+      def stringify(payload)
+        payload.is_a?(Hash) ? payload.transform_keys(&:to_s) : {}
+      end
+
+      def log(method, path, payload)
+        DhanHQ.logger&.warn(
+          JSON.generate(
+            event: "DHAN_DRY_RUN",
+            method: method.to_s.upcase,
+            path: path,
+            payload: payload.is_a?(Hash) ? payload : nil
+          )
+        )
+      end
+    end
+  end
+end

data/lib/DhanHQ/helpers/attribute_helper.rb

@@ -11,6 +11,29 @@ module DhanHQ
       hash.transform_keys { |key| key.to_s.camelize(:lower) }
     end
 
+    # Recursively convert keys from snake_case to camelCase, descending into nested
+    # hashes and through arrays.
+    #
+    # {#camelize_keys} only rewrites the top level, which is correct for the flat
+    # payloads most endpoints take. Endpoints whose body nests objects — the basket
+    # order `orders` array, an alert's `condition` — need this instead, or the nested
+    # fields reach the API still in snake_case and are rejected.
+    #
+    # @param value [Hash, Array, Object] The value to convert
+    # @return [Hash, Array, Object] The converted value; non-collections pass through
+    def deep_camelize_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested), out|
+          out[key.to_s.camelize(:lower)] = deep_camelize_keys(nested)
+        end
+      when Array
+        value.map { |nested| deep_camelize_keys(nested) }
+      else
+        value
+      end
+    end
+
     # Convert keys from snake_case to TitleCase
     #
     # @param hash [Hash] The hash to convert

data/lib/DhanHQ/models/alert_order.rb

@@ -45,7 +45,10 @@ module DhanHQ
         def create(params)
           normalized = snake_case(params)
           validate_params!(normalized, DhanHQ::Contracts::AlertOrderContract)
-          response = resource.create(camelize_keys(normalized))
+          # `condition` and every entry of `orders` are nested objects whose fields the
+          # API expects in camelCase (AlertCondition#comparisonType, #securityId, …), so
+          # a shallow camelize would leave them snake_cased on the wire.
+          response = resource.create(deep_camelize_keys(normalized))
           return nil unless response.is_a?(Hash) && response["alertId"]
 
           find(response["alertId"])
@@ -69,7 +72,7 @@ module DhanHQ
           normalized = snake_case(params)
           validate_params!(normalized, DhanHQ::Contracts::AlertOrderContract)
           payload = normalized.merge(alert_id: alert_id)
-          response = resource.update(alert_id, camelize_keys(payload))
+          response = resource.update(alert_id, deep_camelize_keys(payload))
           return nil unless success_response?(response)
 
           find(alert_id)

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    module GlobalStocks
+      ##
+      # USD fund limit for Global Stocks trading.
+      #
+      # This is a separate balance from the domestic INR limit exposed by
+      # {DhanHQ::Models::Funds}.
+      #
+      # @example
+      #   funds = DhanHQ::Models::GlobalStocks::Funds.fetch
+      #   puts "Available: $#{funds.available_cash}"
+      #   puts "Unsettled: $#{funds.unsettled_cash}"
+      #
+      class Funds < BaseModel
+        HTTP_PATH = "/v2/globalstocks/fundlimit"
+
+        attributes :dhan_client_id, :available_cash, :cash_on_account, :actual_cash,
+                   :settled_cash, :unsettled_cash, :margin_utilized
+
+        # Returns a concise prompt-friendly summary of the USD balance.
+        def to_prompt
+          parts = []
+          parts << "available=$#{available_cash}" if available_cash
+          parts << "settled=$#{settled_cash}" if settled_cash
+          parts << "unsettled=$#{unsettled_cash}" if unsettled_cash
+          parts << "utilized=$#{margin_utilized}" if margin_utilized&.positive?
+          parts.join(", ")
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::Funds]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::Funds.new
+          end
+
+          # Fetches the Global Stocks fund limit.
+          #
+          # @return [Funds]
+          def fetch
+            new(resource.fetch, skip_validation: true)
+          end
+
+          # Convenience accessor for the available USD cash.
+          #
+          # @return [Float]
+          def balance
+            fetch.available_cash.to_f
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    module GlobalStocks
+      ##
+      # A single Global Stocks (US equity) holding.
+      #
+      # Unlike domestic holdings, US holdings report live valuation directly
+      # (+ltp+, +current_value+, +gain_value+), so no quote lookup is needed to
+      # compute unrealised P&L.
+      #
+      # @example Portfolio with unrealised P&L
+      #   holdings = DhanHQ::Models::GlobalStocks::Holding.all
+      #   holdings.each do |h|
+      #     puts "#{h.trading_symbol}: #{h.quantity} @ $#{h.avg_cost_price} (#{h.gain_percentage}%)"
+      #   end
+      #   puts "Total: $#{DhanHQ::Models::GlobalStocks::Holding.total_current_value}"
+      #
+      class Holding < BaseModel
+        HTTP_PATH = "/v2/globalstocks/holdings"
+
+        attributes :dhan_client_id, :trading_symbol, :display_name, :security_id,
+                   :exchange, :quantity, :avg_cost_price, :cost_value, :current_value,
+                   :gain_value, :ltp, :prev_close, :long_term_flag, :last_updated
+
+        # Returns a concise prompt-friendly summary of the holding.
+        def to_prompt
+          parts = ["#{quantity}x #{trading_symbol || security_id}"]
+          parts << "avg_cost=$#{avg_cost_price}" if avg_cost_price&.positive?
+          parts << "ltp=$#{ltp}" if ltp&.positive?
+          parts << "value=$#{current_value}" if current_value
+          parts << "pnl=$#{gain_value} (#{gain_percentage}%)" if gain_value
+          parts.join(", ")
+        end
+
+        # Unrealised gain as a percentage of cost.
+        #
+        # @return [Float] 0.0 when cost value is unknown or zero.
+        def gain_percentage
+          cost = cost_value.to_f
+          return 0.0 if cost.zero?
+
+          (gain_value.to_f / cost * 100).round(2)
+        end
+
+        # @return [Boolean] True when the position is in profit.
+        def profitable?
+          gain_value.to_f.positive?
+        end
+
+        # @return [Boolean] True for a fractional-share position.
+        def fractional?
+          quantity.is_a?(Float) && (quantity % 1 != 0)
+        end
+
+        # Change against the previous close, per share.
+        #
+        # @return [Float, nil] nil when either price is unavailable.
+        def day_change
+          return nil unless ltp && prev_close
+
+          (ltp.to_f - prev_close.to_f).round(4)
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::Holdings]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::Holdings.new
+          end
+
+          # Retrieves all Global Stocks holdings.
+          #
+          # @return [Array<Holding>] Empty array when there are no US holdings.
+          def all
+            response = resource.all
+            return [] unless response.is_a?(Array)
+
+            response.map { |holding| new(holding, skip_validation: true) }
+          rescue DhanHQ::NoHoldingsError
+            []
+          end
+
+          # Total market value of the US portfolio.
+          #
+          # @return [Float]
+          def total_current_value
+            all.sum { |holding| holding.current_value.to_f }
+          end
+
+          # Total unrealised P&L across the US portfolio.
+          #
+          # @return [Float]
+          def total_gain
+            all.sum { |holding| holding.gain_value.to_f }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    module GlobalStocks
+      ##
+      # Margin requirement for a prospective Global Stocks order.
+      #
+      # @example Check affordability before placing
+      #   margin = DhanHQ::Models::GlobalStocks::Margin.calculate(
+      #     security_id: "AAPL", transaction_type: "BUY", price: 180.0, quantity: 10
+      #   )
+      #   puts "Need $#{margin.total_margin}, have $#{margin.available_bal}"
+      #   raise "Insufficient funds" unless margin.sufficient?
+      #
+      class Margin < BaseModel
+        HTTP_PATH = "/v2/globalstocks/margincalculator"
+
+        attributes :insufficient_bal, :brokerage, :leverage, :total_margin, :available_bal
+
+        # Returns a concise prompt-friendly summary of the margin requirement.
+        def to_prompt
+          parts = []
+          parts << "total_margin=$#{total_margin}" if total_margin
+          parts << "available=$#{available_bal}" if available_bal
+          parts << "brokerage=$#{brokerage}" if brokerage
+          parts << "leverage=#{leverage}" if leverage
+          parts << "shortfall=$#{insufficient_bal}" if insufficient_bal.to_f.positive?
+          parts.join(", ")
+        end
+
+        # @return [Boolean] True when the account can fund the order.
+        def sufficient?
+          !insufficient_bal.to_f.positive?
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::MarginCalculator]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::MarginCalculator.new
+          end
+
+          # Calculates the margin required for a Global Stocks order.
+          #
+          # @param params [Hash] `:security_id`, `:transaction_type`, `:price`, `:quantity`
+          # @return [Margin]
+          def calculate(params)
+            new(resource.calculate(params), skip_validation: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    module GlobalStocks
+      ##
+      # Current US market session status.
+      #
+      # @example Gate a strategy on the US session
+      #   status = DhanHQ::Models::GlobalStocks::MarketStatus.fetch
+      #   return unless status.open?
+      #
+      class MarketStatus < BaseModel
+        HTTP_PATH = "/v2/globalstocks/marketstatus"
+
+        attributes :status, :market_open_time, :market_close_time, :holiday_flag
+
+        # Returns a concise prompt-friendly summary of the session.
+        def to_prompt
+          parts = ["US market #{status}"]
+          parts << "open=#{market_open_time}" if market_open_time
+          parts << "close=#{market_close_time}" if market_close_time
+          parts << "holiday" if holiday?
+          parts.join(", ")
+        end
+
+        # @return [Boolean] True when the US market is currently open.
+        def open?
+          status.to_s.casecmp(DhanHQ::Constants::GlobalStocks::MarketStatus::OPEN).zero?
+        end
+
+        # @return [Boolean] True when the US market is currently closed.
+        def closed?
+          !open?
+        end
+
+        # @return [Boolean] True when today is a US market holiday.
+        def holiday?
+          holiday_flag == true
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::MarketStatus]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::MarketStatus.new
+          end
+
+          # Fetches the current US market status.
+          #
+          # @return [MarketStatus]
+          def fetch
+            new(resource.fetch, skip_validation: true)
+          end
+
+          # @return [Boolean] True when the US market is currently open.
+          def open?
+            fetch.open?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Typed models for the Global Stocks (US equities) APIs.
+    #
+    # Global Stocks are a separate book from domestic NSE/BSE trading: separate
+    # order book, holdings, trades and a USD fund limit. They are namespaced so
+    # `Models::GlobalStocks::Holding` can never be confused with the domestic
+    # {DhanHQ::Models::Holding}.
+    module GlobalStocks
+      ##
+      # A single Global Stocks (US equity) order.
+      #
+      # @example Place a limit order for one share of AAPL
+      #   order = DhanHQ::Models::GlobalStocks::Order.place(
+      #     transaction_type: "BUY",
+      #     order_type: "LIMIT",
+      #     security_id: "AAPL",
+      #     quantity: 1,
+      #     price: 180.0
+      #   )
+      #   order.order_id # => "112111182198"
+      #
+      # @example Place a notional ($ value) order
+      #   DhanHQ::Models::GlobalStocks::Order.place(
+      #     transaction_type: "BUY",
+      #     order_type: "AMOUNT",
+      #     security_id: "AAPL",
+      #     amount: 500.0
+      #   )
+      #
+      # @example Fetch the order book
+      #   DhanHQ::Models::GlobalStocks::Order.all.each do |o|
+      #     puts "#{o.trading_symbol} #{o.order_status} #{o.traded_qty}/#{o.quantity}"
+      #   end
+      #
+      class Order < BaseModel
+        HTTP_PATH = "/v2/globalstocks/orders"
+
+        attributes :dhan_client_id, :order_id, :exchange_order_id, :correlation_id,
+                   :transaction_type, :exchange_segment, :product_type, :order_type,
+                   :validity, :trading_symbol, :display_name, :security_id,
+                   :quantity, :remaining_quantity, :traded_qty, :price, :trigger_price,
+                   :avg_traded_price, :order_status, :create_time, :exchange_time,
+                   :update_time, :oms_error_code, :oms_error_description,
+                   :after_market_order, :amount, :lot_size, :fractional_flag,
+                   :leg_name, :child_orders
+
+        # Returns a concise prompt-friendly summary of the order.
+        def to_prompt
+          parts = ["#{transaction_type} #{quantity || amount}x #{trading_symbol || security_id}"]
+          parts << "type=#{order_type}"
+          parts << "price=$#{price}" if price&.positive?
+          parts << "status=#{order_status}" if order_status
+          parts << "traded=#{traded_qty}" if traded_qty&.positive?
+          parts << "avg=$#{avg_traded_price}" if avg_traded_price&.positive?
+          parts << "error=#{oms_error_description}" if oms_error_description
+          parts.join(", ")
+        end
+
+        # @return [Boolean] True when the order can still be modified or cancelled.
+        def pending?
+          [DhanHQ::Constants::OrderStatus::PENDING,
+           DhanHQ::Constants::OrderStatus::TRANSIT,
+           DhanHQ::Constants::OrderStatus::PART_TRADED].include?(order_status)
+        end
+
+        # @return [Boolean] True when the order is fully executed.
+        def traded?
+          order_status == DhanHQ::Constants::OrderStatus::TRADED
+        end
+
+        # @return [Boolean] True when the order reached a terminal state.
+        def closed?
+          [DhanHQ::Constants::OrderStatus::TRADED,
+           DhanHQ::Constants::OrderStatus::CANCELLED,
+           DhanHQ::Constants::OrderStatus::REJECTED,
+           DhanHQ::Constants::OrderStatus::EXPIRED].include?(order_status)
+        end
+
+        # @return [Boolean] True for a notional (dollar-value) order.
+        def notional?
+          order_type == DhanHQ::Constants::GlobalStocks::OrderType::AMOUNT
+        end
+
+        # @return [Boolean] True when the order is for a fractional share quantity.
+        def fractional?
+          return true if fractional_flag
+
+          quantity.is_a?(Float) && (quantity % 1 != 0)
+        end
+
+        # Child legs of a Global Stocks super order, as {Order} instances.
+        #
+        # @return [Array<Order>]
+        def child_legs
+          Array(child_orders).map { |leg| self.class.new(leg, skip_validation: true) }
+        end
+
+        # Modifies this order in place and returns the refreshed record.
+        #
+        # @param params [Hash] Fields to change, in snake_case.
+        # @return [Order, DhanHQ::ErrorObject]
+        def modify(params = {})
+          payload = { transaction_type: transaction_type, order_type: order_type, security_id: security_id }
+                    .merge(params)
+          response = self.class.resource.update(order_id, payload)
+          return DhanHQ::ErrorObject.new(response) unless self.class.send(:successful?, response)
+
+          self.class.find(order_id)
+        end
+
+        # Cancels this order.
+        #
+        # @return [Boolean] True when the API confirms cancellation.
+        def cancel
+          response = self.class.resource.cancel(order_id)
+          status = response.is_a?(Hash) ? (response[:orderStatus] || response[:order_status]) : nil
+          cancelled = status.to_s == DhanHQ::Constants::OrderStatus::CANCELLED
+          DhanHQ.logger&.error("[#{self.class.name}] Cancel failed for order #{order_id}: #{response}") unless cancelled
+          cancelled
+        end
+
+        class << self
+          # @return [DhanHQ::Resources::GlobalStocks::Orders]
+          def resource
+            @resource ||= DhanHQ::Resources::GlobalStocks::Orders.new
+          end
+
+          # Retrieves the current trading day's Global Stocks order book.
+          #
+          # @return [Array<Order>]
+          def all
+            response = resource.all
+            return [] unless response.is_a?(Array)
+
+            response.map { |order| new(order, skip_validation: true) }
+          end
+
+          # Finds a single Global Stocks order by its Dhan order id.
+          #
+          # @param order_id [String]
+          # @return [Order, nil]
+          def find(order_id)
+            response = resource.find(order_id)
+            payload = response.is_a?(Array) ? response.first : response
+            return nil unless payload.is_a?(Hash) && !payload.empty?
+
+            new(payload, skip_validation: true)
+          end
+
+          # Places a new Global Stocks order.
+          #
+          # @param params [Hash] See {DhanHQ::Contracts::GlobalStocksPlaceOrderContract}.
+          # @return [Order, DhanHQ::ErrorObject] The placed order, refetched so the
+          #   caller gets the full record rather than just `{ orderId:, orderStatus: }`.
+          def place(params)
+            DhanHQ.logger&.info("[#{name}] Placing global order: #{params}")
+            response = resource.create(params)
+            return DhanHQ::ErrorObject.new(response) unless successful?(response)
+
+            id = response[:orderId] || response[:order_id]
+            DhanHQ.logger&.info("[#{name}] Global order placed successfully: #{id}")
+            find(id) || new(response, skip_validation: true)
+          end
+          alias create place
+
+          # Cancels a Global Stocks order by id.
+          #
+          # @param order_id [String]
+          # @return [Boolean]
+          def cancel(order_id)
+            response = resource.cancel(order_id)
+            status = response.is_a?(Hash) ? (response[:orderStatus] || response[:order_status]) : nil
+            status.to_s == DhanHQ::Constants::OrderStatus::CANCELLED
+          end
+
+          private
+
+          # An order write succeeded when the API echoed an order id back.
+          def successful?(response)
+            response.is_a?(Hash) && !(response[:orderId] || response[:order_id]).nil?
+          end
+        end
+      end
+    end
+  end
+end