DhanHQ 3.3.0 → 4.0.0

data/lib/dhan_hq.rb

@@ -3,7 +3,11 @@
 require "json"
 require "logger"
 require "zeitwerk"
-require "dotenv/load"
+begin
+  require "dotenv/load"
+rescue LoadError
+  # Dotenv is optional in host applications
+end
 require "faraday"
 # Minimal eager requires for backward-compatible constants.
 # These are widely referenced (e.g. `DhanHQ::BaseAPI`) and should not depend on
@@ -88,9 +92,13 @@ module DhanHQ
     # @return [String]
     BASE_URL = Constants::Urls::REST_API_BASE
     # The current configuration instance.
-    #
-    # @return [DhanHQ::Configuration, nil] The current configuration or `nil` if not set.
-    attr_accessor :configuration
+    attr_reader :configuration
+
+    def configuration=(config)
+      @configuration = config
+      @default_client = nil
+      reset_model_resources!
+    end
 
     attr_writer :logger
 
@@ -106,8 +114,10 @@ module DhanHQ
     # @return [void]
     def configure
       self.configuration ||= Configuration.new
-      yield(configuration)
+      yield(configuration) if block_given?
       self.logger ||= Logger.new($stdout, level: Logger::INFO)
+      @default_client = Client.new(config: configuration)
+      reset_model_resources!
     end
 
     # default logger so calls like DhanHQ.logger&.info never explode
@@ -118,6 +128,18 @@ module DhanHQ
       @logger ||= Logger.new($stdout, level: Logger::INFO)
     end
 
+    # Global default client (used for backward compatibility with class-level APIs)
+    #
+    # @return [DhanHQ::Client]
+    def default_client
+      @default_client ||= Client.new(config: ensure_configuration!)
+    end
+
+    # Resets the global default client
+    def reset_default_client!
+      @default_client = nil
+    end
+
     # Configures the DhanHQ client using environment variables.
     #
     # When credentials are injected via `DHAN_ACCESS_TOKEN` and `DHAN_CLIENT_ID` this helper
@@ -129,6 +151,8 @@ module DhanHQ
     # @return [void]
     def configure_with_env
       self.configuration = Configuration.new
+      @default_client = Client.new(config: configuration)
+      reset_model_resources!
     end
 
     # Ensures configuration exists, bootstrapping from ENV when nil.
@@ -140,9 +164,32 @@ module DhanHQ
       self.configuration ||= Configuration.new
     end
 
-    # Resets the configuration to nil.
+    # Resets the configuration and default client to nil.
     def reset_configuration!
       self.configuration = nil
+      @default_client = nil
+      reset_model_resources!
+    end
+
+    # Clears memoized class-level resource and API instances across all models.
+    def reset_model_resources!
+      models = [
+        BaseModel,
+        Models::Order, Models::Holding, Models::Position, Models::HistoricalData,
+        Models::Trade, Models::OptionChain, Models::Funds, Models::AlertOrder,
+        Models::ForeverOrder, Models::IcebergOrder, Models::SuperOrder, Models::TwapOrder,
+        Models::LedgerEntry, Models::Instrument, Models::Edis, Models::Profile,
+        Models::Margin, Models::MultiOrder, Models::KillSwitch, Models::PnlExit,
+        Models::MarketFeed, Models::ExpiredOptionsData
+      ]
+
+      models.each do |klass|
+        next unless klass.is_a?(Class)
+
+        klass.instance_variables.each do |var|
+          klass.instance_variable_set(var, nil) if var.to_s.end_with?("resource", "api")
+        end
+      end
     end
 
     # Configures the DhanHQ client by fetching credentials from a token endpoint.
@@ -164,39 +211,14 @@ module DhanHQ
     def configure_from_token_endpoint(base_url: nil, bearer_token: nil)
       base_url ||= ENV.fetch("DHAN_TOKEN_ENDPOINT_BASE_URL", nil)
       bearer_token ||= ENV.fetch("DHAN_TOKEN_ENDPOINT_BEARER", nil)
-
       raise DhanHQ::TokenEndpointError, "base_url and bearer_token (or ENV DHAN_TOKEN_ENDPOINT_*) are required" if base_url.to_s.empty? || bearer_token.to_s.empty?
 
-      url = "#{base_url.to_s.chomp("/")}/auth/dhan/token"
-      conn = ::Faraday.new(url: url) do |c|
-        c.request :url_encoded
-        c.adapter ::Faraday.default_adapter
-      end
-
-      response = conn.get("") do |req|
-        req.headers["Authorization"] = "Bearer #{bearer_token}"
-        req.headers["Accept"] = "application/json"
-      end
-
-      unless response.success?
-        body = parse_json_body(response.body)
-        msg = body["error"] || body["message"] || body["errorMessage"] || response.body.to_s
-        raise DhanHQ::TokenEndpointError, "Token endpoint returned #{response.status}: #{msg}"
-      end
-
-      data = parse_json_body(response.body)
-      data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-
-      access_token = data["access_token"] || data[:access_token]
-      client_id = data["client_id"] || data[:client_id]
+      data = fetch_token_endpoint("#{base_url.to_s.chomp("/")}/auth/dhan/token", bearer_token, "Token endpoint")
+      access_token = data["access_token"]
+      client_id = data["client_id"]
       raise DhanHQ::TokenEndpointError, "Token endpoint response missing access_token or client_id" if access_token.to_s.empty? || client_id.to_s.empty?
 
-      self.configuration ||= Configuration.new
-      configuration.access_token = access_token.to_s
-      configuration.client_id = client_id.to_s
-      dhan_base = data["base_url"] || data[:base_url]
-      configuration.base_url = dhan_base.to_s if dhan_base.to_s != ""
-      configuration
+      apply_token_config(access_token, client_id, data["base_url"])
     end
 
     # Configures the DhanHQ client by fetching credentials from a dashboard API.
@@ -208,6 +230,18 @@ module DhanHQ
     def configure_from_dashboard(bearer_token:, url: "http://localhost:3011/api/dhan_access_token")
       raise DhanHQ::TokenEndpointError, "bearer_token is required" if bearer_token.to_s.empty?
 
+      data = fetch_token_endpoint(url, bearer_token, "Dashboard")
+      access_token = data["access_token"] || data["accessToken"] || data["dhan_access_token"] || data["dhanaccesstoken"]
+      client_id = data["client_id"] || data["clientId"] || data["dhan_client_id"] || data["dhanClientId"]
+      client_id ||= configuration&.client_id || ENV.fetch("DHAN_CLIENT_ID", nil)
+
+      raise DhanHQ::TokenEndpointError, "Dashboard response missing access_token (tried access_token, dhan_access_token, dhanaccesstoken)" if access_token.to_s.empty?
+      raise DhanHQ::TokenEndpointError, "Dashboard response missing client_id, and no fallback client_id was found in config or ENV['DHAN_CLIENT_ID']" if client_id.to_s.empty?
+
+      apply_token_config(access_token, client_id, data["base_url"] || data["baseUrl"])
+    end
+
+    def fetch_token_endpoint(url, bearer_token, label)
       conn = ::Faraday.new(url: url) do |c|
         c.request :url_encoded
         c.adapter ::Faraday.default_adapter
@@ -221,24 +255,18 @@ module DhanHQ
       unless response.success?
         body = parse_json_body(response.body)
         msg = body["error"] || body["message"] || body["errorMessage"] || response.body.to_s
-        raise DhanHQ::TokenEndpointError, "Dashboard returned #{response.status}: #{msg}"
+        raise DhanHQ::TokenEndpointError, "#{label} returned #{response.status}: #{msg}"
       end
 
       data = parse_json_body(response.body)
-      data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-
-      access_token = data["access_token"] || data["accessToken"] || data["dhan_access_token"] || data["dhanaccesstoken"]
-      client_id = data["client_id"] || data["clientId"] || data["dhan_client_id"] || data["dhanClientId"]
-      client_id ||= self.configuration&.client_id || ENV.fetch("DHAN_CLIENT_ID", nil)
-
-      raise DhanHQ::TokenEndpointError, "Dashboard response missing access_token (tried access_token, dhan_access_token, dhanaccesstoken)" if access_token.to_s.empty?
-      raise DhanHQ::TokenEndpointError, "Dashboard response missing client_id, and no fallback client_id was found in config or ENV['DHAN_CLIENT_ID']" if client_id.to_s.empty?
+      data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+    end
 
+    def apply_token_config(access_token, client_id, base_url)
       self.configuration ||= Configuration.new
       configuration.access_token = access_token.to_s
       configuration.client_id = client_id.to_s
-      dhan_base = data["base_url"] || data["baseUrl"]
-      configuration.base_url = dhan_base.to_s if dhan_base.to_s != ""
+      configuration.base_url = base_url.to_s if base_url.to_s != ""
       configuration
     end
 

data/lib/generators/dhanhq/install/install_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Dhanhq
+  # Scaffolds a DhanHQ initializer, a sample order-placing service object, and
+  # a Sidekiq worker + ActionCable channel for streaming market data.
+  #
+  #   rails generate dhanhq:install
+  #
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def create_initializer
+      template "initializer.rb", "config/initializers/dhanhq.rb"
+    end
+
+    def create_order_service
+      template "place_order_service.rb", "app/services/dhan/orders/place_order.rb"
+    end
+
+    def create_market_feed_worker
+      template "market_feed_worker.rb", "app/workers/dhan_market_feed_worker.rb"
+    end
+
+    def create_market_feed_channel
+      template "market_feed_channel.rb", "app/channels/dhan_market_feed_channel.rb"
+    end
+
+    def show_post_install_message
+      say ""
+      say "DhanHQ installed! Next steps:", :green
+      say "  1. Add your credentials:"
+      say "       rails credentials:edit"
+      say "       dhanhq:"
+      say "         client_id: \"your_client_id\""
+      say "         access_token: \"your_access_token\""
+      say "  2. Set LIVE_TRADING=true before placing real orders (see docs/CONFIGURATION.md)"
+      say "  3. Start the market feed: DhanMarketFeedWorker.perform_async"
+      say ""
+      say "Full reference: https://github.com/shubhamtaywade82/dhanhq-client/blob/main/docs/RAILS_INTEGRATION.md"
+      say ""
+    end
+  end
+end

data/lib/generators/dhanhq/install/templates/initializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "dhan_hq"
+
+if (creds = Rails.application.credentials.dig(:dhanhq))
+  ENV["DHAN_CLIENT_ID"]    ||= creds[:client_id]
+  ENV["DHAN_ACCESS_TOKEN"] ||= creds[:access_token]
+end
+
+DhanHQ.configure_with_env
+
+log_level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase
+DhanHQ.logger.level = Logger.const_get(log_level)
+
+# Full optional configuration (base_url, ws_order_url, partner auth, timeouts,
+# DHAN_WS_DEBUG, ...) is documented in:
+#   https://github.com/shubhamtaywade82/dhanhq-client/blob/main/docs/CONFIGURATION.md
+#   https://github.com/shubhamtaywade82/dhanhq-client/blob/main/docs/RAILS_INTEGRATION.md

data/lib/generators/dhanhq/install/templates/market_feed_channel.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class DhanMarketFeedChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "dhan_market_feed"
+  end
+end

data/lib/generators/dhanhq/install/templates/market_feed_worker.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Keeps a DhanHQ market feed connection open and broadcasts ticks over
+# ActionCable. Start it with DhanMarketFeedWorker.perform_async -- the job
+# blocks for the life of the connection rather than completing immediately,
+# so Sidekiq's dashboard reflects whether the feed is actually running.
+#
+# retry: false because there is nothing to retry: the underlying
+# DhanHQ::WS::Client already reconnects and re-subscribes on its own.
+class DhanMarketFeedWorker
+  include Sidekiq::Worker
+  sidekiq_options retry: false
+
+  def perform(mode = "quote")
+    client = DhanHQ::WS.connect(mode: mode.to_sym) do |tick|
+      ActionCable.server.broadcast("dhan_market_feed", tick)
+    end
+
+    client.on(:reconnect) { |info| Rails.logger.warn("[DhanMarketFeedWorker] reconnect ##{info[:attempt]}") }
+    client.on(:error) { |message| Rails.logger.error("[DhanMarketFeedWorker] #{message}") }
+
+    loop do
+      sleep 30
+      break unless client.connected?
+    end
+  end
+end

data/lib/generators/dhanhq/install/templates/place_order_service.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Dhan
+  module Orders
+    # Places a Dhan order via the bang variant, so a rejection raises a
+    # specific, catchable error instead of Order.place's ambiguous
+    # nil/false/ErrorObject return.
+    class PlaceOrder
+      def initialize(params)
+        @params = params
+      end
+
+      def call
+        DhanHQ::Models::Order.place!(@params)
+      rescue DhanHQ::OrderError => e
+        Rails.logger.error("Dhan order rejected: #{e.message}")
+        raise
+      rescue DhanHQ::RiskViolation => e
+        Rails.logger.warn("Dhan risk check blocked the order: #{e.message}")
+        raise
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-26 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,98 +16,98 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: bindata
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: dry-validation
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: eventmachine
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -128,46 +128,47 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: rotp
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description: A production-grade Ruby SDK for Dhan API v2 built for algo trading, portfolio
-  monitoring, and live trading systems. Provides typed models, token lifecycle management,
-  dry-validation contracts, resilient WebSocket streaming, and safety-focused order
-  workflows for Ruby applications.
+        version: '2.6'
+description: A production-grade Ruby SDK and Ruby client for Dhan API v2 built for
+  algorithmic trading, portfolio monitoring, and live trading systems on NSE, BSE
+  and MCX. Provides typed models, token lifecycle management, dry-validation contracts,
+  resilient WebSocket streaming with auto-reconnect, and safety-focused order workflows
+  for Ruby on Rails and standalone Ruby applications.
 email:
 - shubhamtaywade82@gmail.com
 executables:
@@ -228,6 +229,10 @@ files:
 - lib/DhanHQ/auth/token_generator.rb
 - lib/DhanHQ/auth/token_manager.rb
 - lib/DhanHQ/auth/token_renewal.rb
+- lib/DhanHQ/backtest.rb
+- lib/DhanHQ/backtest/result.rb
+- lib/DhanHQ/backtest/runner.rb
+- lib/DhanHQ/backtest/trade.rb
 - lib/DhanHQ/client.rb
 - lib/DhanHQ/concerns/bang_writes.rb
 - lib/DhanHQ/concerns/order_audit.rb
@@ -283,6 +288,7 @@ files:
 - lib/DhanHQ/helpers/response_helper.rb
 - lib/DhanHQ/helpers/validation_helper.rb
 - lib/DhanHQ/indicators.rb
+- lib/DhanHQ/jobs/place_order_job.rb
 - lib/DhanHQ/json_loader.rb
 - lib/DhanHQ/market_data.rb
 - lib/DhanHQ/market_data/market_snapshot.rb
@@ -433,6 +439,11 @@ files:
 - lib/dhanhq/analysis/multi_timeframe_analyzer.rb
 - lib/dhanhq/analysis/options_buying_advisor.rb
 - lib/dhanhq/contracts/options_buying_advisor_contract.rb
+- lib/generators/dhanhq/install/install_generator.rb
+- lib/generators/dhanhq/install/templates/initializer.rb
+- lib/generators/dhanhq/install/templates/market_feed_channel.rb
+- lib/generators/dhanhq/install/templates/market_feed_worker.rb
+- lib/generators/dhanhq/install/templates/place_order_service.rb
 - lib/rubocop/cop/dhanhq/use_constants.rb
 - lib/ta.rb
 - lib/ta/candles.rb
@@ -469,14 +480,15 @@ files:
 - skills/dhanhq-ruby/scripts/resolve_security.rb
 - skills/dhanhq-ruby/scripts/trade_logger.rb
 - skills/dhanhq-ruby/scripts/validate_order.rb
-homepage: https://github.com/shubhamtaywade82/dhanhq-client
+homepage: https://shubhamtaywade82.github.io/dhanhq-client/
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/shubhamtaywade82/dhanhq-client
+  homepage_uri: https://shubhamtaywade82.github.io/dhanhq-client/
   source_code_uri: https://github.com/shubhamtaywade82/dhanhq-client
   changelog_uri: https://github.com/shubhamtaywade82/dhanhq-client/blob/main/CHANGELOG.md
+  documentation_uri: https://shubhamtaywade82.github.io/dhanhq-client/
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -496,5 +508,6 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: The Ruby SDK for Dhan API v2 with REST, WebSocket, and trading workflows.
+summary: Production-grade Ruby SDK for Dhan API v2 with REST APIs, WebSocket market
+  data, token lifecycle management, dry-validation contracts and trading workflows.
 test_files: []