DhanHQ 3.1.0 → 3.2.1

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

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