DhanHQ 3.1.0 → 3.2.1

data/lib/DhanHQ/contracts/global_stocks_place_order_contract.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "global_stocks_order_contract"
+
+module DhanHQ
+  module Contracts
+    # Validation contract for POST /v2/globalstocks/orders.
+    #
+    # @example
+    #   DhanHQ::Contracts::GlobalStocksPlaceOrderContract.new.call(
+    #     transaction_type: "BUY",
+    #     order_type: "LIMIT",
+    #     security_id: "AAPL",
+    #     quantity: 1.0,
+    #     price: 180.0
+    #   )
+    class GlobalStocksPlaceOrderContract < GlobalStocksOrderContract
+      params do
+        required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+        required(:order_type).filled(:string, included_in?: ORDER_TYPES)
+        required(:security_id).filled(:string, max_size?: 50)
+
+        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:quantity).maybe(:float, gt?: 0)
+        optional(:price).maybe(:float, gteq?: 0)
+        optional(:trigger_price).maybe(:float, gt?: 0)
+        optional(:stop_loss_price).maybe(:float, gt?: 0)
+        optional(:target_price).maybe(:float, gt?: 0)
+        optional(:amount).maybe(:float, gt?: 0)
+        optional(:after_market_order).maybe(:bool)
+        optional(:dhan_client_id).maybe(:string)
+      end
+
+      # AMOUNT orders are notional: they carry `amount` instead of `quantity`.
+      # Every other order type needs a quantity.
+      rule(:order_type, :quantity, :amount) do
+        if values[:order_type] == DhanHQ::Constants::GlobalStocks::OrderType::AMOUNT
+          key(:amount).failure("must be present for AMOUNT orders") unless values[:amount]
+        elsif !values[:quantity]
+          key(:quantity).failure("must be present unless order_type is AMOUNT")
+        end
+      end
+
+      rule(:order_type, :price) do
+        price = values[:price]
+
+        key(:price).failure("must be greater than 0 for LIMIT orders") if PRICED_ORDER_TYPES.include?(values[:order_type]) && !price&.positive?
+        key(:price).failure("must be a finite number") if price.is_a?(Float) && (price.nan? || price.infinite?)
+      end
+
+      rule(:order_type, :trigger_price) do
+        key(:trigger_price).failure("must be present for STOP_LOSS orders") if TRIGGERED_ORDER_TYPES.include?(values[:order_type]) && !values[:trigger_price]
+      end
+
+      # Mirrors the domestic super-order relationship checks: a BUY exits above
+      # entry and stops out below it, and vice versa for a SELL.
+      rule(:transaction_type, :price, :target_price, :stop_loss_price) do
+        price = values[:price]
+        next unless price&.positive?
+
+        target = values[:target_price]
+        stop = values[:stop_loss_price]
+
+        case values[:transaction_type]
+        when DhanHQ::Constants::TransactionType::BUY
+          key(:target_price).failure("must be greater than price for BUY orders") if target && target <= price
+          key(:stop_loss_price).failure("must be less than price for BUY orders") if stop && stop >= price
+        when DhanHQ::Constants::TransactionType::SELL
+          key(:target_price).failure("must be less than price for SELL orders") if target && target >= price
+          key(:stop_loss_price).failure("must be greater than price for SELL orders") if stop && stop <= price
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/historical_data_contract.rb

@@ -18,36 +18,16 @@ module DhanHQ
         optional(:oi).maybe(:bool)
       end
 
-      rule(:from_date) do
-        next unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/)
-
-        # Only validate weekend for pure date strings (YYYY-MM-DD)
-        if value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
-          d = Date.parse(value)
-          key.failure("must be a valid trading date (no weekend dates)") unless trading_day?(d)
-        end
-      rescue Date::Error
-        key.failure("invalid date format")
-      end
-
       rule(:from_date, :to_date) do
         next unless values[:from_date].match?(/\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/) &&
                     values[:to_date].match?(/\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/)
 
         from_date = DateTime.parse(values[:from_date])
         to_date = DateTime.parse(values[:to_date])
-        key.failure("from_date must be before to_date") if from_date >= to_date
+        key.failure("from_date must be before or equal to to_date") if from_date > to_date
       rescue Date::Error
         key.failure("invalid date format")
       end
-
-      private
-
-      def trading_day?(date)
-        return false unless date.is_a?(Date)
-
-        (1..5).cover?(date.wday)
-      end
     end
   end
 end

data/lib/DhanHQ/contracts/multi_order_contract.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "dry-validation"
+require_relative "base_contract"
+
+module DhanHQ
+  module Contracts
+    # Validation contract for POST /v2/alerts/multi/orders (basket orders).
+    #
+    # A multi order places up to {MAX_ORDERS} unconditional orders in a single
+    # request. Each leg carries a +sequence+ that identifies it in the response.
+    class MultiOrderContract < BaseContract
+      # Maximum legs the API accepts in one basket.
+      MAX_ORDERS = 15
+
+      TRANSACTION_TYPES = DhanHQ::Constants::TransactionType::ALL
+      EXCHANGE_SEGMENTS = DhanHQ::Constants::ExchangeSegment::ALL
+      PRODUCT_TYPES     = DhanHQ::Constants::ProductType::MARGIN_CALC_ALL
+      ORDER_TYPES       = DhanHQ::Constants::OrderType::ALL
+      VALIDITY_TYPES    = DhanHQ::Constants::Validity::ALL
+      AMO_TIMES         = DhanHQ::Constants::AmoTime::ALL
+
+      params do
+        optional(:dhan_client_id).maybe(:string)
+
+        required(:orders).array(:hash) do
+          required(:sequence).filled(:string)
+          required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+          required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+
+          optional(:product_type).maybe(:string, included_in?: PRODUCT_TYPES)
+          optional(:order_type).maybe(:string, included_in?: ORDER_TYPES)
+          optional(:validity).maybe(:string, included_in?: VALIDITY_TYPES)
+          optional(:security_id).maybe(:string)
+          optional(:quantity).maybe(:integer, gt?: 0)
+          optional(:price).maybe(:float, gt?: 0)
+          optional(:trigger_price).maybe(:float, gt?: 0)
+          optional(:disclosed_quantity).maybe(:integer, gteq?: 0)
+          optional(:correlation_id).maybe(:string, max_size?: 30)
+          optional(:after_market_order).maybe(:bool)
+          optional(:amo_time).maybe(:string, included_in?: AMO_TIMES)
+        end
+      end
+
+      rule(:orders) do
+        key.failure("must contain at least one order") if value.empty?
+        key.failure("cannot contain more than #{MAX_ORDERS} orders") if value.size > MAX_ORDERS
+
+        sequences = value.map { |order| order[:sequence] }
+        key.failure("sequence values must be unique") if sequences.uniq.size != sequences.size
+      end
+
+      # Order types that require a trigger price on each leg.
+      TRIGGERED_ORDER_TYPES = [
+        DhanHQ::Constants::OrderType::STOP_LOSS,
+        DhanHQ::Constants::OrderType::STOP_LOSS_MARKET
+      ].freeze
+
+      # Per-leg price/trigger consistency, mirroring the single-order contract.
+      rule(:orders) do
+        value.each_with_index do |order, index|
+          type = order[:order_type]
+
+          key([:orders, index, :price]).failure("must be present for LIMIT orders") if type == DhanHQ::Constants::OrderType::LIMIT && !order[:price]
+          key([:orders, index, :price]).failure("must not be provided for MARKET orders") if type == DhanHQ::Constants::OrderType::MARKET && order[:price]
+
+          next unless TRIGGERED_ORDER_TYPES.include?(type) && !order[:trigger_price]
+
+          key([:orders, index, :trigger_price]).failure("must be present for STOP_LOSS orders")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/trade_history_contract.rb

@@ -14,9 +14,6 @@ module DhanHQ
 
       rule(:from_date) do
         key.failure("must be in YYYY-MM-DD format (e.g., 2024-01-15)") unless valid_date_format?(value)
-        next unless valid_date_format?(value)
-
-        key.failure("must be a valid trading date (no weekend dates)") unless trading_day?(Date.parse(value))
       end
 
       rule(:to_date) do
@@ -28,7 +25,7 @@ module DhanHQ
         to = values[:to_date]
         next unless valid_date_format?(from) && valid_date_format?(to)
 
-        key.failure("from_date must be before to_date") if Date.parse(from) >= Date.parse(to)
+        key.failure("from_date must be before or equal to to_date") if Date.parse(from) > Date.parse(to)
       rescue Date::Error
         key.failure("invalid date format")
       end
@@ -43,10 +40,6 @@ module DhanHQ
       rescue Date::Error
         false
       end
-
-      def trading_day?(date)
-        date.is_a?(Date) && (1..5).cover?(date.wday)
-      end
     end
   end
 end

data/lib/DhanHQ/dry_run/ledger.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module DhanHQ
+  module DryRun
+    # Remembers the orders a dry run pretended to place, so a follow-up read for one
+    # of those simulated ids can be answered locally.
+    #
+    # This exists because the high-level models re-fetch after placing:
+    # `Models::Order.place` and `GlobalStocks::Order.place` both call `find(order_id)`
+    # to return the complete record. Without a ledger that GET would leave the process
+    # carrying a `DRYRUN-…` id to the live API, which is both a real network call and a
+    # guaranteed miss — so dry run would only have worked for direct
+    # {DhanHQ::Client#request} calls, not the API people actually use.
+    #
+    # Entries are per-process and capped; a long rehearsal evicts its oldest records
+    # rather than growing without bound.
+    class Ledger
+      # Maximum simulated orders retained before the oldest are evicted.
+      MAX_ENTRIES = 500
+
+      def initialize(max_entries: MAX_ENTRIES)
+        @max_entries = max_entries
+        @records = {}
+        @mutex = Mutex.new
+      end
+
+      # Process-wide ledger used by {DhanHQ::DryRun::Simulator}.
+      #
+      # @return [Ledger]
+      def self.instance
+        @instance ||= new
+      end
+
+      # Records a simulated order.
+      #
+      # @param order_id [String] The simulated order id
+      # @param record [Hash] The response to replay for reads of that id
+      # @return [Hash] The stored record
+      def record(order_id, record)
+        @mutex.synchronize do
+          @records.delete(order_id)
+          @records[order_id] = record
+          @records.shift while @records.size > @max_entries
+          record
+        end
+      end
+
+      # Fetches a previously simulated order.
+      #
+      # @param order_id [String]
+      # @return [Hash, nil] nil when the id was never simulated in this process
+      def fetch(order_id)
+        @mutex.synchronize { @records[order_id] }
+      end
+
+      # @return [Integer] Number of retained records
+      def size
+        @mutex.synchronize { @records.size }
+      end
+
+      # Drops every retained record. Intended for test isolation.
+      #
+      # @return [void]
+      def clear
+        @mutex.synchronize { @records.clear }
+      end
+    end
+  end
+end

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)
@@ -93,7 +96,7 @@ module DhanHQ
         handle_api_response(response, success_key: new_record? ? "alertId" : nil)
       end
 
-      def destroy # rubocop:disable Naming/PredicateMethod
+      def destroy
         return false if new_record?
 
         response = self.class.resource.delete(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