DhanHQ 3.1.0 → 3.2.0

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/dhanhq/analysis/options_buying_advisor.rb

@@ -100,13 +100,13 @@ module DhanHQ
         # Choose the nearest expiry (first element); adjust selection if API returns sorted differently
         expiry = expiries.first
         raw = DhanHQ::Models::OptionChain.fetch(underlying_scrip: sid.to_i, underlying_seg: seg, expiry: expiry)
-        oc = raw[:oc] || {}
-        # Transform OC structure into advisor-friendly array [{ strike:, ce: {...}, pe: {...} }]
-        @data[:option_chain] = oc.map do |strike, strike_data|
+        strikes = raw[:strikes] || []
+        # Transform normalized strikes into advisor-friendly array [{ strike:, ce: {...}, pe: {...} }]
+        @data[:option_chain] = strikes.map do |entry|
           {
-            strike: strike.to_f,
-            ce: normalize_leg(strike_data["ce"] || {}),
-            pe: normalize_leg(strike_data["pe"] || {})
+            strike: entry[:strike].to_f,
+            ce: normalize_leg(entry[:call] || {}),
+            pe: normalize_leg(entry[:put] || {})
           }
         end
       rescue StandardError
@@ -114,11 +114,12 @@ module DhanHQ
       end
 
       def normalize_leg(cepe)
+        greeks = cepe[:greeks] || {}
         {
-          ltp: cepe["last_price"], bid: cepe["best_bid_price"], ask: cepe["best_ask_price"],
-          iv: cepe["iv"], oi: cepe["oi"], volume: cepe["volume"],
-          delta: cepe["delta"], gamma: cepe["gamma"], vega: cepe["vega"], theta: cepe["theta"],
-          lot_size: cepe["lot_size"], tradable: true
+          ltp: cepe[:last_price], bid: cepe[:top_bid_price], ask: cepe[:top_ask_price],
+          iv: cepe[:implied_volatility], oi: cepe[:oi], volume: cepe[:volume],
+          delta: greeks[:delta], gamma: greeks[:gamma], vega: greeks[:vega], theta: greeks[:theta],
+          security_id: cepe[:security_id], tradable: true
         }
       end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -176,21 +176,12 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- ".rubocop_todo.yml"
-- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - GUIDE.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- TAGS
 - config/initializers/order_update_hub.rb
-- core
-- diagram.html
 - docs/API_DOCS_GAPS.md
 - docs/API_VERIFICATION.md
 - docs/AUTHENTICATION.md
@@ -220,9 +211,14 @@ files:
 - exe/dhanhq-mcp
 - lib/DhanHQ.rb
 - lib/DhanHQ/agent.rb
+- lib/DhanHQ/agent/key_coercion.rb
 - lib/DhanHQ/agent/order_preview.rb
 - lib/DhanHQ/agent/policy.rb
+- lib/DhanHQ/agent/tool.rb
+- lib/DhanHQ/agent/tool_catalogue.rb
+- lib/DhanHQ/agent/tool_handlers.rb
 - lib/DhanHQ/agent/tool_registry.rb
+- lib/DhanHQ/agent/tool_schemas.rb
 - lib/DhanHQ/ai.rb
 - lib/DhanHQ/ai/context_builder.rb
 - lib/DhanHQ/ai/prompt_helpers.rb
@@ -239,6 +235,10 @@ files:
 - lib/DhanHQ/contracts/edis_contract.rb
 - lib/DhanHQ/contracts/expired_options_data_contract.rb
 - lib/DhanHQ/contracts/forever_order_contract.rb
+- lib/DhanHQ/contracts/global_stocks_estimator_contract.rb
+- lib/DhanHQ/contracts/global_stocks_modify_order_contract.rb
+- lib/DhanHQ/contracts/global_stocks_order_contract.rb
+- lib/DhanHQ/contracts/global_stocks_place_order_contract.rb
 - lib/DhanHQ/contracts/historical_data_contract.rb
 - lib/DhanHQ/contracts/iceberg_order_contract.rb
 - lib/DhanHQ/contracts/instrument_list_contract.rb
@@ -246,6 +246,7 @@ files:
 - lib/DhanHQ/contracts/margin_calculator_contract.rb
 - lib/DhanHQ/contracts/market_feed_contract.rb
 - lib/DhanHQ/contracts/modify_order_contract.rb
+- lib/DhanHQ/contracts/multi_order_contract.rb
 - lib/DhanHQ/contracts/multi_scrip_margin_calc_request_contract.rb
 - lib/DhanHQ/contracts/option_chain_contract.rb
 - lib/DhanHQ/contracts/order_contract.rb
@@ -263,6 +264,8 @@ files:
 - lib/DhanHQ/core/base_model.rb
 - lib/DhanHQ/core/base_resource.rb
 - lib/DhanHQ/core/error_handler.rb
+- lib/DhanHQ/dry_run/ledger.rb
+- lib/DhanHQ/dry_run/simulator.rb
 - lib/DhanHQ/error_object.rb
 - lib/DhanHQ/errors.rb
 - lib/DhanHQ/events.rb
@@ -288,6 +291,13 @@ files:
 - lib/DhanHQ/models/expired_options_data.rb
 - lib/DhanHQ/models/forever_order.rb
 - lib/DhanHQ/models/funds.rb
+- lib/DhanHQ/models/global_stocks/funds.rb
+- lib/DhanHQ/models/global_stocks/holding.rb
+- lib/DhanHQ/models/global_stocks/margin.rb
+- lib/DhanHQ/models/global_stocks/market_status.rb
+- lib/DhanHQ/models/global_stocks/order.rb
+- lib/DhanHQ/models/global_stocks/order_estimate.rb
+- lib/DhanHQ/models/global_stocks/trade.rb
 - lib/DhanHQ/models/historical_data.rb
 - lib/DhanHQ/models/holding.rb
 - lib/DhanHQ/models/iceberg_order.rb
@@ -297,6 +307,7 @@ files:
 - lib/DhanHQ/models/ledger_entry.rb
 - lib/DhanHQ/models/margin.rb
 - lib/DhanHQ/models/market_feed.rb
+- lib/DhanHQ/models/multi_order.rb
 - lib/DhanHQ/models/option_chain.rb
 - lib/DhanHQ/models/order.rb
 - lib/DhanHQ/models/order_update.rb
@@ -321,6 +332,12 @@ files:
 - lib/DhanHQ/resources/expired_options_data.rb
 - lib/DhanHQ/resources/forever_orders.rb
 - lib/DhanHQ/resources/funds.rb
+- lib/DhanHQ/resources/global_stocks/funds.rb
+- lib/DhanHQ/resources/global_stocks/holdings.rb
+- lib/DhanHQ/resources/global_stocks/margin_calculator.rb
+- lib/DhanHQ/resources/global_stocks/market_status.rb
+- lib/DhanHQ/resources/global_stocks/orders.rb
+- lib/DhanHQ/resources/global_stocks/trades.rb
 - lib/DhanHQ/resources/historical_data.rb
 - lib/DhanHQ/resources/holdings.rb
 - lib/DhanHQ/resources/iceberg_orders.rb
@@ -329,6 +346,7 @@ files:
 - lib/DhanHQ/resources/kill_switch.rb
 - lib/DhanHQ/resources/margin_calculator.rb
 - lib/DhanHQ/resources/market_feed.rb
+- lib/DhanHQ/resources/multi_orders.rb
 - lib/DhanHQ/resources/option_chain.rb
 - lib/DhanHQ/resources/orders.rb
 - lib/DhanHQ/resources/pnl_exit.rb
@@ -370,6 +388,7 @@ files:
 - lib/DhanHQ/strategy/base.rb
 - lib/DhanHQ/utils/network_inspector.rb
 - lib/DhanHQ/version.rb
+- lib/DhanHQ/write_paths.rb
 - lib/DhanHQ/ws.rb
 - lib/DhanHQ/ws/base_connection.rb
 - lib/DhanHQ/ws/client.rb
@@ -416,35 +435,6 @@ files:
 - lib/ta/market_calendar.rb
 - lib/ta/technical_analysis.rb
 - sig/DhanHQ.rbs
-- skills/dhanhq-ruby/SKILL.md
-- skills/dhanhq-ruby/examples/fetch_option_chain.rb
-- skills/dhanhq-ruby/examples/gtt_forever_order.rb
-- skills/dhanhq-ruby/examples/historical_data_analysis.rb
-- skills/dhanhq-ruby/examples/iron_condor.rb
-- skills/dhanhq-ruby/examples/live_feed_setup.rb
-- skills/dhanhq-ruby/examples/margin_check.rb
-- skills/dhanhq-ruby/examples/order_management.rb
-- skills/dhanhq-ruby/examples/place_equity_order.rb
-- skills/dhanhq-ruby/examples/place_fno_order.rb
-- skills/dhanhq-ruby/examples/portfolio_summary.rb
-- skills/dhanhq-ruby/examples/super_order_with_sl.rb
-- skills/dhanhq-ruby/references/backtesting-with-dhan.md
-- skills/dhanhq-ruby/references/common-workflows.md
-- skills/dhanhq-ruby/references/error-codes.md
-- skills/dhanhq-ruby/references/funds.md
-- skills/dhanhq-ruby/references/instruments.md
-- skills/dhanhq-ruby/references/live-feed.md
-- skills/dhanhq-ruby/references/market-data.md
-- skills/dhanhq-ruby/references/option-chain.md
-- skills/dhanhq-ruby/references/options-analysis-patterns.md
-- skills/dhanhq-ruby/references/orders.md
-- skills/dhanhq-ruby/references/portfolio.md
-- skills/dhanhq-ruby/references/scanx-data.md
-- skills/dhanhq-ruby/scripts/dhan_helpers.rb
-- skills/dhanhq-ruby/scripts/resolve_security.rb
-- skills/dhanhq-ruby/scripts/trade_logger.rb
-- skills/dhanhq-ruby/scripts/validate_order.rb
-- watchlist.csv
 homepage: https://github.com/shubhamtaywade82/dhanhq-client
 licenses:
 - MIT

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,50 +0,0 @@
-inherit_from: .rubocop_todo.yml
-
-plugins:
-  - rubocop-rspec
-  - rubocop-performance
-
-require:
-  - rubocop-rake
-  - ./lib/rubocop/cop/dhanhq/use_constants.rb
-
-AllCops:
-  TargetRubyVersion: 3.2
-  NewCops: enable
-  Exclude:
-    - "skills/**/*"
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-# RSpec
-RSpec/MultipleExpectations:
-  Max: 5
-
-RSpec/ExampleLength:
-  Max: 15
-
-RSpec/MultipleMemoizedHelpers:
-  Max: 10
-
-Lint/ScriptPermission:
-  Exclude:
-    - "bin/**/*"
-
-Metrics/AbcSize:
-  Exclude:
-    - "bin/call_all_endpoints.rb"
-
-Layout/LineLength:
-  Exclude:
-    - "bin/call_all_endpoints.rb"
-
-DhanHQ/UseConstants:
-  Enabled: true
-  Exclude:
-    - "lib/DhanHQ/constants.rb"
-    - "lib/DhanHQ/ws/segments.rb"
-    - "spec/**/*"