DhanHQ 3.1.0 → 3.2.1

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/risk/pipeline.rb

@@ -51,14 +51,12 @@ module DhanHQ
       # @param type [Symbol] :equity or :options
       # @return [true] if all checks pass
       # @raise [DhanHQ::RiskViolation] on first failure
-      # rubocop:disable Naming/PredicateMethod
       def self.run!(instrument:, args:, now: Time.now, type: :equity)
         run_checks!(CHECKS, instrument, args, now)
         run_checks!(OPTION_CHECKS, instrument, args, now) if type == :options
         run_checks!(DAILY_CHECKS, instrument, args, now)
         true
       end
-      # rubocop:enable Naming/PredicateMethod
 
       def self.run_checks!(checks, instrument, args, now)
         checks.each do |check|

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.1"
 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

data/lib/DhanHQ/ws/client.rb

@@ -26,6 +26,9 @@ module DhanHQ
         @state = SubState.new
         @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
         @started = Concurrent::AtomicBoolean.new(false)
+        @last_message_at = Concurrent::AtomicReference.new(nil)
+        @connected_at = Concurrent::AtomicReference.new(nil)
+        @reconnects = Concurrent::AtomicFixnum.new(0)
 
         token = DhanHQ.configuration.resolved_access_token
         raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
@@ -43,7 +46,8 @@ module DhanHQ
         return self if @started.true?
 
         @started.make_true
-        @conn = Connection.new(url: @url, mode: @mode, bus: @bus, state: @state) do |binary|
+        @conn = Connection.new(url: @url, mode: @mode, bus: @bus, state: @state,
+                               on_event: method(:handle_connection_event)) do |binary|
           tick = Decoder.decode(binary)
           emit(:tick, tick) if tick
         end
@@ -90,6 +94,80 @@ module DhanHQ
         @conn&.open? || false
       end
 
+      # Timestamp of the most recently received frame.
+      #
+      # A feed can be "connected" and still be dead — the socket stays open while
+      # the server has stopped publishing. Long-running daemons should watch this
+      # rather than {#connected?} alone.
+      #
+      # @return [Time, nil] nil until the first frame arrives.
+      def last_message_at
+        @last_message_at.get
+      end
+
+      # Seconds since the last frame arrived.
+      #
+      # @return [Float, nil] nil until the first frame arrives.
+      def seconds_since_last_message
+        stamp = last_message_at
+        return nil unless stamp
+
+        Time.now - stamp
+      end
+
+      # Whether the feed looks alive: connected and delivering frames recently.
+      #
+      # @param stale_after [Numeric] Seconds of silence after which the feed is
+      #   considered stale. The server pings roughly every 10 seconds, so the
+      #   default allows several missed intervals.
+      # @return [Boolean]
+      def healthy?(stale_after: 45)
+        return false unless connected?
+
+        idle = seconds_since_last_message
+        idle.nil? || idle <= stale_after
+      end
+
+      # Timestamp of the current connection's establishment.
+      #
+      # @return [Time, nil]
+      def connected_at
+        @connected_at.get
+      end
+
+      # Number of times the connection has been re-established since {#start}.
+      #
+      # @return [Integer]
+      def reconnect_count
+        @reconnects.value
+      end
+
+      # Instruments currently subscribed, as `"SEGMENT:SECURITY_ID"` strings.
+      #
+      # Survives reconnects: the connection replays this set on every new session.
+      #
+      # @return [Array<String>]
+      def subscriptions
+        @state.snapshot
+      end
+
+      # Point-in-time health snapshot, suitable for a monitoring endpoint or log line.
+      #
+      # @return [Hash]
+      def health
+        {
+          mode: @mode,
+          started: @started.true?,
+          connected: connected?,
+          healthy: healthy?,
+          connected_at: connected_at,
+          last_message_at: last_message_at,
+          seconds_since_last_message: seconds_since_last_message,
+          reconnect_count: reconnect_count,
+          subscription_count: subscriptions.size
+        }
+      end
+
       # Subscribes to updates for a single instrument.
       #
       # @param segment [String, Symbol, Integer]
@@ -154,9 +232,27 @@ module DhanHQ
 
       # Registers a callback for a given event.
       #
-      # @param event [Symbol] Event name (:tick, :open, :close, :error).
+      # Supported events:
+      #
+      # - +:tick+ — a decoded market data packet.
+      # - +:open+ — the socket connected. Payload: `{ resubscribed: [...] }`.
+      # - +:reconnect+ — the socket re-connected after a drop. Payload:
+      #   `{ attempt: Integer, resubscribed: [...] }`. Subscriptions are replayed
+      #   automatically before this fires; use it to re-seed derived state such as
+      #   candle builders or to alert.
+      # - +:close+ — the socket closed. Payload:
+      #   `{ code:, reason:, reconnecting: Boolean }`.
+      # - +:error+ — a socket-level error. Payload: the error message.
+      #
+      # @param event [Symbol] Event name.
       # @yieldparam payload [Object] Event payload.
       # @return [DhanHQ::WS::Client] self.
+      #
+      # @example React to a reconnect
+      #   client.on(:reconnect) do |info|
+      #     logger.warn "feed reconnected (attempt #{info[:attempt]}), " \
+      #                 "#{info[:resubscribed].size} instruments restored"
+      #   end
       def on(event, &blk)
         @callbacks[event] << blk
         self
@@ -164,6 +260,25 @@ module DhanHQ
 
       private
 
+      # Bridges connection-level lifecycle events onto the client's callback bus and
+      # updates the health counters. +:message+ is internal bookkeeping only — the
+      # decoded payload reaches users as +:tick+.
+      def handle_connection_event(event, payload)
+        case event
+        when :message
+          @last_message_at.set(Time.now)
+          return
+        when :open
+          @connected_at.set(Time.now)
+        when :reconnect
+          @reconnects.increment
+        when :close
+          @connected_at.set(nil)
+        end
+
+        emit(event, payload)
+      end
+
       def prune(hash) = { ExchangeSegment: hash[:ExchangeSegment], SecurityId: hash[:SecurityId] }
 
       def emit(event, payload)

data/lib/DhanHQ/ws/connection.rb

@@ -23,13 +23,18 @@ module DhanHQ
       # @param bus [DhanHQ::WS::CmdBus] Command queue feeding subscription
       #   changes.
       # @param state [DhanHQ::WS::SubState] Tracks subscription status.
+      # @param on_event [Proc, nil] Optional callable invoked as
+      #   +on_event.call(event, payload)+ for lifecycle events (+:open+, +:close+,
+      #   +:error+, +:reconnect+). Lets the owning client surface connection state
+      #   to user callbacks.
       # @yield [binary]
       # @yieldparam binary [String] Raw binary frame received from the socket.
-      def initialize(url:, mode:, bus:, state:, &on_binary)
+      def initialize(url:, mode:, bus:, state:, on_event: nil, &on_binary)
         @url = url
         @mode = mode
         @bus = bus
         @state = state
+        @on_event = on_event
         @on_binary = on_binary
         @stop = false
         @stopping = false
@@ -90,11 +95,41 @@ module DhanHQ
 
       private
 
+      # Notifies the owning client of a lifecycle event. Never lets a user callback
+      # take down the connection thread.
+      def notify(event, payload = nil)
+        @on_event&.call(event, payload)
+      rescue StandardError => e
+        DhanHQ.logger&.error("[DhanHQ::WS] on_event(#{event}) raised #{e.class}: #{e.message}")
+      end
+
+      # Restores subscriptions and starts the command drain for a freshly opened
+      # socket, then reports the transition.
+      #
+      # @param session [Integer] 1-based index of this connection attempt. Anything
+      #   past the first is a reconnect.
+      def handle_open(session)
+        DhanHQ.logger&.info("[DhanHQ::WS] open")
+
+        # The server keeps no subscription state across connections, so the desired set
+        # is replayed on every new session. See SubState#resubscribe_payload.
+        snapshot = @state.resubscribe_payload
+        send_sub(snapshot) unless snapshot.empty?
+        @timer = EM.add_periodic_timer(0.25) { drain_and_send }
+
+        # :reconnect lets callers re-seed derived state (candle builders, caches)
+        # and see exactly which instruments were restored for them.
+        notify(:reconnect, { attempt: session - 1, resubscribed: snapshot }) if session > 1
+        notify(:open, { resubscribed: snapshot })
+      end
+
       def loop_run
         backoff = 2.0
+        sessions = 0
         until @stop
           failed = false
           got_429 = false
+          sessions += 1
 
           # respect any active cool-off window
           sleep (@cooloff_until - Time.now).ceil if @cooloff_until && Time.now < @cooloff_until
@@ -103,18 +138,10 @@ module DhanHQ
             EM.run do
               @ws = Faye::WebSocket::Client.new(@url, nil, headers: default_headers)
 
-              @ws.on :open do |_|
-                DhanHQ.logger&.info("[DhanHQ::WS] open")
-                # re-subscribe snapshot on reconnect
-                snapshot = @state.snapshot.map do |k|
-                  seg, sid = k.split(":")
-                  { ExchangeSegment: seg, SecurityId: sid }
-                end
-                send_sub(snapshot) unless snapshot.empty?
-                @timer = EM.add_periodic_timer(0.25) { drain_and_send }
-              end
+              @ws.on(:open) { |_| handle_open(sessions) }
 
               @ws.on :message do |ev|
+                notify(:message, nil)
                 @on_binary&.call(ev.data) # raw frames to decoder
               end
 
@@ -131,12 +158,14 @@ module DhanHQ
                   failed  = (ev.code != 1000)
                   got_429 = ev.reason.to_s.include?("429")
                 end
+                notify(:close, { code: ev.code, reason: ev.reason, reconnecting: failed })
                 EM.stop
               end
 
               @ws.on :error do |ev|
                 DhanHQ.logger&.error("[DhanHQ::WS] error #{ev.message}")
                 failed = true
+                notify(:error, ev.message)
               end
             end
           rescue StandardError => e

data/lib/DhanHQ/ws/sub_state.rb

@@ -51,6 +51,20 @@ module DhanHQ
         @mutex.synchronize { @set.to_a }
       end
 
+      # The desired subscriptions rendered as instrument hashes, ready to be sent as a
+      # subscribe frame.
+      #
+      # The server keeps no subscription state across connections, so a reconnecting
+      # client replays this on every new session.
+      #
+      # @return [Array<Hash>] Instruments with +:ExchangeSegment+ and +:SecurityId+.
+      def resubscribe_payload
+        snapshot.map do |key|
+          segment, security_id = key.split(":")
+          { ExchangeSegment: segment, SecurityId: security_id }
+        end
+      end
+
       private
 
       def key_for(instrument) = "#{instrument[:ExchangeSegment]}:#{instrument[:SecurityId]}"

data/lib/dhan_hq.rb

@@ -26,6 +26,10 @@ module DhanHQ
   LOADER = Zeitwerk::Loader.new
   LOADER.tag = "dhanhq"
   LOADER.inflector.inflect(
+    # Without this, Zeitwerk looks for DhanHQ::Ai while ai.rb defines DhanHQ::AI, so
+    # DhanHQ::AI::PromptHelpers raised NameError unless something had already loaded
+    # the file by hand — which only mcp/server.rb did.
+    "ai" => "AI",
     "api_helper" => "APIHelper",
     "auth_api" => "AuthAPI",
     "base_api" => "BaseAPI",