DhanHQ 2.2.2 → 2.4.0

data/lib/DhanHQ/contracts/trade_by_order_id_contract.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    # Validation contract for trade-by-order-id requests.
+    class TradeByOrderIdContract < BaseContract
+      params do
+        required(:order_id).filled(:string, min_size?: 1)
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/trade_contract.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "date"
-
 module DhanHQ
   module Contracts
     ##
@@ -10,68 +8,5 @@ module DhanHQ
       # No input validation needed for GET requests
       # These contracts are mainly for documentation and future extensibility
     end
-
-    ##
-    # Validation contract for trade history requests
-    class TradeHistoryContract < BaseContract
-      params do
-        required(:from_date).filled(:string)
-        required(:to_date).filled(:string)
-        optional(:page).filled(:integer, gteq?: 0)
-      end
-
-      rule(:from_date) do
-        key.failure("must be in YYYY-MM-DD format (e.g., 2024-01-15)") unless valid_date_format?(value)
-        key.failure("must be a valid trading date (no weekend dates)") if valid_date_format?(value) && !trading_day?(Date.parse(value))
-      end
-
-      rule(:to_date) do
-        key.failure("must be in YYYY-MM-DD format (e.g., 2024-01-15)") unless valid_date_format?(value)
-      end
-
-      rule(:from_date, :to_date) do
-        from_date_valid = valid_date_format?(values[:from_date])
-        to_date_valid = valid_date_format?(values[:to_date])
-
-        if values[:from_date] && values[:to_date] && from_date_valid && to_date_valid
-          begin
-            from_date = Date.parse(values[:from_date])
-            to_date = Date.parse(values[:to_date])
-
-            key.failure("from_date must be before to_date") if from_date >= to_date
-          rescue Date::Error
-            key.failure("invalid date format")
-          end
-        end
-      end
-
-      private
-
-      def valid_date_format?(date_string)
-        return false unless date_string.is_a?(String)
-        return false unless date_string.match?(/\A\d{4}-\d{2}-\d{2}\z/)
-
-        begin
-          Date.parse(date_string)
-          true
-        rescue Date::Error
-          false
-        end
-      end
-
-      def trading_day?(date)
-        return false unless date.is_a?(Date)
-
-        (1..5).cover?(date.wday)
-      end
-    end
-
-    ##
-    # Validation contract for trade by order ID requests
-    class TradeByOrderIdContract < BaseContract
-      params do
-        required(:order_id).filled(:string, min_size?: 1)
-      end
-    end
   end
 end

data/lib/DhanHQ/contracts/trade_history_contract.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "date"
+
+module DhanHQ
+  module Contracts
+    # Validation contract for trade history requests.
+    class TradeHistoryContract < BaseContract
+      params do
+        required(:from_date).filled(:string)
+        required(:to_date).filled(:string)
+        optional(:page).filled(:integer, gteq?: 0)
+      end
+
+      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
+        key.failure("must be in YYYY-MM-DD format (e.g., 2024-01-15)") unless valid_date_format?(value)
+      end
+
+      rule(:from_date, :to_date) do
+        from = values[:from_date]
+        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)
+      rescue Date::Error
+        key.failure("invalid date format")
+      end
+
+      private
+
+      def valid_date_format?(date_string)
+        return false unless date_string.is_a?(String) && date_string.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        Date.parse(date_string)
+        true
+      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/core/auth_api.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module DhanHQ
+  # Faraday client for Dhan auth endpoints.
+  #
+  # This class intentionally lives at the top-level namespace so it autoloads
+  # cleanly from `lib/DhanHQ/core/auth_api.rb` with Zeitwerk `collapse`.
+  class AuthAPI
+    BASE_URL = "https://auth.dhan.co"
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |faraday|
+        faraday.request :url_encoded
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/DhanHQ/core/base_resource.rb

@@ -11,7 +11,7 @@ module DhanHQ
     #
     # @return [Array<Hash>, Hash]
     def all
-      get(self.class::HTTP_PATH)
+      get("")
     end
 
     # Retrieves a single resource by identifier.
@@ -19,7 +19,7 @@ module DhanHQ
     # @param id [String, Integer]
     # @return [Hash]
     def find(id)
-      get("#{self.class::HTTP_PATH}/#{id}")
+      get("/#{id}")
     end
 
     # Creates a new resource instance.
@@ -27,7 +27,7 @@ module DhanHQ
     # @param params [Hash]
     # @return [Hash]
     def create(params)
-      post(self.class::HTTP_PATH, params: params)
+      post("", params: params)
     end
 
     # Updates an existing resource.
@@ -36,7 +36,7 @@ module DhanHQ
     # @param params [Hash]
     # @return [Hash]
     def update(id, params)
-      put("#{self.class::HTTP_PATH}/#{id}", params: params)
+      put("/#{id}", params: params)
     end
 
     # Deletes a resource by identifier.
@@ -44,7 +44,7 @@ module DhanHQ
     # @param id [String, Integer]
     # @return [Hash]
     def delete(id)
-      super("#{self.class::HTTP_PATH}/#{id}")
+      super("/#{id}")
     end
   end
 end

data/lib/DhanHQ/helpers/request_helper.rb

@@ -44,7 +44,7 @@ module DhanHQ
         client_id = DhanHQ.configuration&.client_id
         unless client_id
           raise DhanHQ::InvalidAuthenticationError,
-                "client_id is required for DATA APIs but not set. Please configure DhanHQ with CLIENT_ID."
+                "client_id is required for DATA APIs but not set. Please configure DhanHQ with DHAN_CLIENT_ID."
         end
         headers["client-id"] = client_id
       end

data/lib/DhanHQ/models/alert_order.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../contracts/alert_order_contract"
+
+module DhanHQ
+  module Models
+    # Model for alert/conditional orders. CRUD via AlertOrders resource; validated by AlertOrderContract.
+    class AlertOrder < BaseModel
+      HTTP_PATH = "/alerts/orders"
+
+      attributes :alert_id, :exchange_segment, :security_id, :condition,
+                 :trigger_price, :order_type, :transaction_type, :quantity,
+                 :price, :status, :created_at
+
+      class << self
+        def api_type
+          :order_api
+        end
+
+        def resource
+          @resource ||= DhanHQ::Resources::AlertOrders.new
+        end
+
+        def validation_contract
+          Contracts::AlertOrderContract
+        end
+
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |attrs| new(attrs, skip_validation: true) }
+        end
+
+        def find(alert_id)
+          response = resource.find(alert_id)
+          return nil unless response.is_a?(Hash) || (response.is_a?(Array) && response.any?)
+
+          payload = response.is_a?(Array) ? response.first : response
+          new(payload, skip_validation: true)
+        end
+
+        def create(params)
+          normalized = snake_case(params)
+          validate_params!(normalized, DhanHQ::Contracts::AlertOrderContract)
+          response = resource.create(camelize_keys(normalized))
+          return nil unless response.is_a?(Hash) && response["alertId"]
+
+          find(response["alertId"])
+        end
+      end
+
+      def id
+        alert_id&.to_s
+      end
+
+      def save # rubocop:disable Naming/PredicateMethod
+        return false unless valid?
+
+        payload = to_request_params
+        response = if new_record?
+                     self.class.resource.create(camelize_keys(payload))
+                   else
+                     self.class.resource.update(id, camelize_keys(payload))
+                   end
+        return false if new_record? && !(response.is_a?(Hash) && response["alertId"])
+        return false if !new_record? && !success_response?(response)
+
+        @attributes.merge!(normalize_keys(response))
+        assign_attributes
+        true
+      end
+
+      def destroy # rubocop:disable Naming/PredicateMethod
+        return false if new_record?
+
+        response = self.class.resource.delete(id)
+        success_response?(response)
+      end
+      alias delete destroy
+    end
+  end
+end

data/lib/DhanHQ/models/token_response.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "time"
+
+module DhanHQ
+  module Models
+    # Represents a Dhan API token response with expiry tracking and validation.
+    #
+    # TokenResponse wraps the response from Dhan's token generation and renewal
+    # endpoints, providing convenient methods for checking token validity and
+    # determining when refresh is needed.
+    #
+    # @example From token generation
+    #   response = Auth.generate_access_token(
+    #     dhan_client_id: "123",
+    #     pin: "1234",
+    #     totp: "654321"
+    #   )
+    #   token = TokenResponse.new(response)
+    #   token.expired?       # => false
+    #   token.expires_in     # => 86400 (seconds)
+    #   token.needs_refresh? # => false
+    #
+    # @example Checking token status
+    #   if token.needs_refresh?(buffer_seconds: 600)
+    #     # Refresh token 10 minutes before expiry
+    #     new_token = Auth.renew_token(...)
+    #   end
+    #
+    # @attr_reader [String] client_id Dhan client ID
+    # @attr_reader [String] client_name Dhan client name
+    # @attr_reader [String] ucc Unique client code
+    # @attr_reader [Boolean] power_of_attorney POA status
+    # @attr_reader [String] access_token The authentication token
+    # @attr_reader [Time] expiry_time Token expiration timestamp
+    class TokenResponse
+      attr_reader :client_id,
+                  :client_name,
+                  :ucc,
+                  :power_of_attorney,
+                  :access_token,
+                  :expiry_time
+
+      def initialize(data)
+        data = normalize_keys(data)
+
+        @client_id = data["dhanClientId"]
+        @client_name = data["dhanClientName"]
+        @ucc = data["dhanClientUcc"]
+        @power_of_attorney = data["givenPowerOfAttorney"]
+        @access_token = data["accessToken"]
+        @expiry_time = parse_time(data["expiryTime"])
+      end
+
+      def expired?
+        return true unless expiry_time
+
+        Time.now >= expiry_time
+      end
+
+      def expires_in
+        return 0 unless expiry_time
+
+        expiry_time - Time.now
+      end
+
+      def needs_refresh?(buffer_seconds: 300)
+        return true unless expiry_time
+
+        Time.now >= (expiry_time - buffer_seconds)
+      end
+
+      private
+
+      def normalize_keys(data)
+        return {} unless data.is_a?(Hash)
+
+        data.transform_keys(&:to_s)
+      end
+
+      def parse_time(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        Time.parse(value.to_s)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/alert_orders.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource for alert/conditional orders per API docs: /alerts/orders (GET/POST/PUT/DELETE).
+    class AlertOrders < BaseResource
+      API_TYPE  = :order_api
+      HTTP_PATH = "/alerts/orders"
+    end
+  end
+end

data/lib/DhanHQ/resources/edis.rb

@@ -2,40 +2,25 @@
 
 module DhanHQ
   module Resources
-    # Resource client for electronic DIS flows.
+    # Resource for EDIS per https://dhanhq.co/docs/v2/edis/
+    # GET /edis/tpin, POST /edis/form (body: isin, qty, exchange, segment, bulk),
+    # POST /edis/bulkform, GET /edis/inquire/{isin}.
     class Edis < BaseAPI
-      # EDIS endpoints are served from the trading API.
-      API_TYPE = :order_api
-      # Base path for EDIS endpoints.
-      HTTP_PATH = "/v2/edis"
+      API_TYPE  = :order_api
+      HTTP_PATH = "/edis"
 
-      # Creates a TPIN request form.
-      #
-      # @param params [Hash]
-      # @return [Hash]
       def form(params)
         post("/form", params: params)
       end
 
-      # Bulk EDIS form submission.
-      #
-      # @param params [Hash]
-      # @return [Hash]
       def bulk_form(params)
         post("/bulkform", params: params)
       end
 
-      # Generates a TPIN for the client.
-      #
-      # @return [Hash]
       def tpin
         get("/tpin")
       end
 
-      # Checks the EDIS status for a given ISIN.
-      #
-      # @param isin [String]
-      # @return [Hash]
       def inquire(isin)
         get("/inquire/#{isin}")
       end

data/lib/DhanHQ/resources/ip_setup.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource for IP whitelist per API docs: GET /ip/getIP, POST /ip/setIP, PUT /ip/modifyIP.
+    class IPSetup < BaseAPI
+      API_TYPE  = :order_api
+      HTTP_PATH = "/ip"
+
+      def current
+        get("/getIP")
+      end
+
+      def set(ip:)
+        post("/setIP", params: { ip: ip })
+      end
+
+      def update(ip:)
+        put("/modifyIP", params: { ip: ip })
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/trader_control.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource for trader control (kill switch): status (GET), enable/disable (POST /trader-control).
+    class TraderControl < BaseAPI
+      API_TYPE  = :order_api
+      HTTP_PATH = "/trader-control"
+
+      def status
+        get("")
+      end
+
+      def enable
+        post("", params: { action: "ENABLE" })
+      end
+
+      def disable
+        post("", params: { action: "DISABLE" })
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "2.2.2"
+  VERSION = "2.4.0"
 end

data/lib/dhan_hq.rb

@@ -1,92 +1,46 @@
 # frozen_string_literal: true
 
-require "dotenv/load"
+require "json"
 require "logger"
-
-# Helper Methods
+require "zeitwerk"
+require "dotenv/load"
+# Minimal eager requires for backward-compatible constants.
+# These are widely referenced (e.g. `DhanHQ::BaseAPI`) and should not depend on
+# the autoloader being fully configured.
 require_relative "DhanHQ/helpers/api_helper"
 require_relative "DhanHQ/helpers/attribute_helper"
 require_relative "DhanHQ/helpers/validation_helper"
 require_relative "DhanHQ/helpers/request_helper"
 require_relative "DhanHQ/helpers/response_helper"
-require_relative "DhanHQ/json_loader"
-
 require_relative "DhanHQ/core/base_api"
-require_relative "DhanHQ/core/base_resource"
 require_relative "DhanHQ/core/base_model"
-require_relative "DhanHQ/core/error_handler"
-
-require_relative "DhanHQ/version"
-require_relative "DhanHQ/errors"
-require_relative "DhanHQ/error_object"
-
-require_relative "DhanHQ/client"
-require_relative "DhanHQ/configuration"
-require_relative "DhanHQ/rate_limiter"
-require_relative "DhanHQ/auth"
-
-# Contracts
-require_relative "DhanHQ/contracts/base_contract"
-require_relative "DhanHQ/contracts/historical_data_contract"
-require_relative "DhanHQ/contracts/margin_calculator_contract"
-require_relative "DhanHQ/contracts/position_conversion_contract"
-require_relative "DhanHQ/contracts/slice_order_contract"
-require_relative "DhanHQ/contracts/trade_contract"
-require_relative "DhanHQ/contracts/expired_options_data_contract"
-
-# Resources
-require_relative "DhanHQ/resources/option_chain"
-require_relative "DhanHQ/resources/orders"
-require_relative "DhanHQ/resources/forever_orders"
-require_relative "DhanHQ/resources/super_orders"
-require_relative "DhanHQ/resources/funds"
-require_relative "DhanHQ/resources/holdings"
-require_relative "DhanHQ/resources/positions"
-require_relative "DhanHQ/resources/statements"
-require_relative "DhanHQ/resources/trades"
-require_relative "DhanHQ/resources/historical_data"
-require_relative "DhanHQ/resources/margin_calculator"
-require_relative "DhanHQ/resources/market_feed"
-require_relative "DhanHQ/resources/instruments"
-require_relative "DhanHQ/resources/edis"
-require_relative "DhanHQ/resources/kill_switch"
-require_relative "DhanHQ/resources/profile"
-require_relative "DhanHQ/resources/expired_options_data"
-
-# Models
-require_relative "DhanHQ/models/order"
-require_relative "DhanHQ/models/funds"
-require_relative "DhanHQ/models/option_chain"
-require_relative "DhanHQ/models/forever_order"
-require_relative "DhanHQ/models/super_order"
-require_relative "DhanHQ/models/historical_data"
-require_relative "DhanHQ/models/market_feed"
-require_relative "DhanHQ/models/instrument"
-require_relative "DhanHQ/models/position"
-require_relative "DhanHQ/models/holding"
-require_relative "DhanHQ/models/ledger_entry"
-require_relative "DhanHQ/models/trade"
-require_relative "DhanHQ/models/margin"
-require_relative "DhanHQ/models/edis"
-require_relative "DhanHQ/models/kill_switch"
-require_relative "DhanHQ/models/profile"
-require_relative "DhanHQ/models/order_update"
-require_relative "DhanHQ/models/expired_options_data"
-
-require_relative "DhanHQ/constants"
-require_relative "DhanHQ/ws"
-require_relative "DhanHQ/ws/singleton_lock"
-require_relative "ta"
-require_relative "dhanhq/analysis/multi_timeframe_analyzer"
-require_relative "dhanhq/analysis/helpers/bias_aggregator"
-require_relative "dhanhq/analysis/helpers/moneyness_helper"
-require_relative "dhanhq/contracts/options_buying_advisor_contract"
-require_relative "dhanhq/analysis/options_buying_advisor"
+require_relative "DhanHQ/core/base_resource"
 
 # The top-level module for the DhanHQ client library.
 #
 # Provides configuration management for setting credentials and API-related settings.
 module DhanHQ
+  LOADER = Zeitwerk::Loader.new
+  LOADER.tag = "dhanhq"
+  LOADER.inflector.inflect(
+    "api_helper" => "APIHelper",
+    "auth_api" => "AuthAPI",
+    "base_api" => "BaseAPI",
+    "ip_setup" => "IPSetup",
+    "json_loader" => "JSONLoader",
+    "ws" => "WS"
+  )
+  LOADER.push_dir(File.join(__dir__, "DhanHQ"), namespace: self)
+  LOADER.push_dir(File.join(__dir__, "dhanhq"), namespace: self)
+  LOADER.collapse(File.join(__dir__, "DhanHQ", "core"))
+  LOADER.collapse(File.join(__dir__, "DhanHQ", "helpers"))
+  LOADER.collapse(File.join(__dir__, "dhanhq", "analysis", "helpers"))
+  LOADER.ignore(
+    File.join(__dir__, "DhanHQ", "errors.rb"),
+    File.join(__dir__, "DhanHQ", "version.rb")
+  )
+  LOADER.setup
+
   class Error < StandardError; end
 
   class << self
@@ -127,7 +81,7 @@ module DhanHQ
 
     # Configures the DhanHQ client using environment variables.
     #
-    # When credentials are injected via `ACCESS_TOKEN` and `CLIENT_ID` this helper
+    # When credentials are injected via `DHAN_ACCESS_TOKEN` and `DHAN_CLIENT_ID` this helper
     # can be used to initialise a configuration without a block.
     #
     # @example
@@ -136,8 +90,8 @@ module DhanHQ
     # @return [void]
     def configure_with_env
       self.configuration ||= Configuration.new
-      configuration.access_token = ENV.fetch("ACCESS_TOKEN", nil)
-      configuration.client_id = ENV.fetch("CLIENT_ID", nil)
+      configuration.access_token = ENV.fetch("DHAN_ACCESS_TOKEN", nil)
+      configuration.client_id = ENV.fetch("DHAN_CLIENT_ID", nil)
       configuration.base_url = ENV.fetch("DHAN_BASE_URL", BASE_URL)
       configuration.ws_version = ENV.fetch("DHAN_WS_VERSION", configuration.ws_version || 2).to_i
       configuration.ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", configuration.ws_order_url)