DhanHQ 2.3.0 → 2.5.0

data/lib/DhanHQ/auth/token_renewal.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Auth
+    # Backward-compatible wrapper for token renewal.
+    # Delegates to module-level Auth.renew_token.
+    class TokenRenewal
+      def renew
+        config = DhanHQ.configuration
+        raise Errors::AuthenticationError, "Missing configuration" unless config
+
+        access_token = config.resolved_access_token
+        dhan_client_id = config.client_id
+        raise Errors::AuthenticationError, "Missing dhanClientId (client_id)" if dhan_client_id.to_s.strip.empty?
+
+        response = Auth.renew_token(
+          access_token: access_token,
+          client_id: dhan_client_id
+        )
+
+        Models::TokenResponse.new(response)
+      end
+    end
+  end
+end

data/lib/DhanHQ/auth.rb

@@ -2,52 +2,112 @@
 
 require "faraday"
 require "json"
+require "rotp"
+require_relative "errors"
 
 module DhanHQ
-  # Helpers for Dhan authentication APIs.
-  # The gem does not implement API key/secret consent flows or Partner consent;
-  # use Dhan Web or your own OAuth flow to obtain tokens, then pass them via
-  # configuration. This module supports refreshing web-generated tokens only.
+  # Module-level helpers for Dhan authentication APIs.
+  #
+  # Supports:
+  # - Generating access tokens via TOTP (for automated systems)
+  # - Renewing web-generated tokens (web-only tokens)
+  #
+  # @example Generate token with TOTP
+  #   totp = DhanHQ::Auth.generate_totp(ENV["DHAN_TOTP_SECRET"])
+  #   response = DhanHQ::Auth.generate_access_token(
+  #     dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  #     pin: ENV["DHAN_PIN"],
+  #     totp: totp
+  #   )
+  #   token = response["accessToken"]
+  #
+  # @example Renew web token
+  #   response = DhanHQ::Auth.renew_token(
+  #     access_token: current_token,
+  #     client_id: ENV["DHAN_CLIENT_ID"]
+  #   )
   module Auth
-    # Refreshes a web-generated access token (24h validity).
-    # Calls POST /v2/RenewToken; expires the current token and returns a new one.
-    # Only valid for tokens generated from Dhan Web (not API key flow).
+    AUTH_BASE_URL = "https://auth.dhan.co"
+    API_BASE_URL  = "https://api.dhan.co/v2"
+
+    # Generates an access token using TOTP authentication.
     #
-    # @param access_token [String] Current JWT from Dhan Web
-    # @param client_id [String] Dhan client ID (dhanClientId)
-    # @param base_url [String, nil] API base URL (default: DhanHQ.configuration.base_url)
-    # @return [HashWithIndifferentAccess] Response with :access_token and :expiry_time (if present)
-    # @raise [DhanHQ::Error] On HTTP or API error
-    def self.renew_token(access_token, client_id, base_url: nil)
-      base_url ||= DhanHQ.configuration&.base_url || Configuration::BASE_URL
-      url = "#{base_url.chomp("/")}/RenewToken"
-
-      conn = Faraday.new(url: url) do |c|
-        c.request :json
-        c.response :json, content_type: /\bjson$/
-        c.adapter Faraday.default_adapter
+    # POST https://auth.dhan.co/app/generateAccessToken
+    #
+    # @param dhan_client_id [String] Your Dhan client ID
+    # @param pin [String] Your 6-digit Dhan PIN
+    # @param totp [String] 6-digit TOTP code (or use generate_totp helper)
+    # @return [Hash] Response hash with accessToken, expiryTime, etc.
+    # @raise [DhanHQ::InvalidAuthenticationError] On authentication failure
+    def self.generate_access_token(dhan_client_id:, pin:, totp:)
+      conn = build_connection(AUTH_BASE_URL)
+
+      response = conn.post("/app/generateAccessToken") do |req|
+        req.headers["Accept"] = "application/json"
+
+        req.params = {
+          dhanClientId: dhan_client_id,
+          pin: pin,
+          totp: totp
+        }
       end
 
-      response = conn.get("") do |req|
+      handle_response(response, context: "GenerateAccessToken")
+    end
+
+    # Renews a web-generated access token (24h validity).
+    #
+    # POST https://api.dhan.co/v2/RenewToken
+    #
+    # ⚠️ Works ONLY for tokens generated from Dhan Web dashboard.
+    # For TOTP-generated tokens, regenerate instead of renewing.
+    #
+    # @param access_token [String] Current JWT access token
+    # @param client_id [String] Dhan client ID (dhanClientId)
+    # @return [Hash] Response hash with new accessToken and expiryTime
+    # @raise [DhanHQ::InvalidAuthenticationError] On renewal failure
+    def self.renew_token(access_token:, client_id:)
+      conn = build_connection(API_BASE_URL)
+
+      response = conn.post("/RenewToken") do |req|
         req.headers["access-token"] = access_token
         req.headers["dhanClientId"] = client_id
         req.headers["Accept"] = "application/json"
       end
 
+      handle_response(response, context: "RenewToken")
+    end
+
+    # Generates a 6-digit TOTP code from a secret.
+    #
+    # @param secret [String] TOTP secret (from authenticator app setup)
+    # @return [String] 6-digit TOTP code
+    def self.generate_totp(secret)
+      ROTP::TOTP.new(secret).now
+    end
+
+    private
+
+    def self.build_connection(base_url)
+      Faraday.new(url: base_url) do |c|
+        c.request :url_encoded
+        c.response :json, content_type: /\bjson$/
+        c.adapter Faraday.default_adapter
+      end
+    end
+    private_class_method :build_connection
+
+    def self.handle_response(response, context:)
       unless response.success?
-        body = begin
-          JSON.parse(response.body.to_s)
-        rescue JSON::ParserError
-          {}
-        end
+        body = response.body.is_a?(Hash) ? response.body : {}
         error_message = body["errorMessage"] || body["message"] || response.body.to_s
-        raise DhanHQ::InvalidAuthenticationError, "RenewToken failed: #{response.status} #{error_message}"
+
+        raise DhanHQ::InvalidAuthenticationError,
+              "#{context} failed: #{response.status} #{error_message}"
       end
 
-      data = response.body
-      data = JSON.parse(data) if data.is_a?(String)
-      result = data.is_a?(Hash) ? data : {}
-      result.with_indifferent_access
+      response.body.is_a?(Hash) ? response.body : {}
     end
+    private_class_method :handle_response
   end
 end

data/lib/DhanHQ/client.rb

@@ -29,6 +29,8 @@ module DhanHQ
     # @return [Faraday::Connection] The connection instance used for API requests.
     attr_reader :connection
 
+    attr_reader :token_manager
+
     # Initializes a new DhanHQ Client instance with a Faraday connection.
     #
     # @example Create a new client:
@@ -38,9 +40,9 @@ module DhanHQ
     # @return [DhanHQ::Client] A new client instance.
     # @raise [DhanHQ::Error] If configuration is invalid or rate limiter initialization fails
     def initialize(api_type:)
-      # Configure from ENV if CLIENT_ID is present (backward compatible behavior)
+      # Configure from ENV if DHAN_CLIENT_ID is present (backward compatible behavior)
       # Validation happens at request time in build_headers, not here
-      DhanHQ.configure_with_env if ENV.fetch("CLIENT_ID", nil)
+      DhanHQ.configure_with_env if ENV.fetch("DHAN_CLIENT_ID", nil)
 
       # Use shared rate limiter instance per API type to ensure proper coordination
       @rate_limiter = RateLimiter.for(api_type)
@@ -72,6 +74,7 @@ module DhanHQ
     # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] Parsed JSON response.
     # @raise [DhanHQ::Error] If an HTTP error occurs.
     def request(method, path, payload, retries: 3)
+      @token_manager&.ensure_valid_token!
       @rate_limiter.throttle! # **Ensure we don't hit rate limit before calling API**
 
       attempt = 0
@@ -159,6 +162,43 @@ module DhanHQ
       request(:delete, path, params)
     end
 
+    def generate_access_token(dhan_client_id:, pin:, totp: nil, totp_secret: nil)
+      token = Auth::TokenGenerator.new.generate(
+        dhan_client_id: dhan_client_id,
+        pin: pin,
+        totp: totp,
+        totp_secret: totp_secret
+      )
+
+      DhanHQ.configure do |config|
+        config.access_token = token.access_token
+        config.client_id = token.client_id if token.client_id.to_s.strip != ""
+      end
+
+      token
+    end
+
+    def renew_access_token
+      token = Auth::TokenRenewal.new.renew
+
+      DhanHQ.configure do |config|
+        config.access_token = token.access_token
+        config.client_id = token.client_id if token.client_id.to_s.strip != ""
+      end
+
+      token
+    end
+
+    def enable_auto_token_management!(dhan_client_id:, pin:, totp_secret:)
+      @token_manager = Auth::TokenManager.new(
+        dhan_client_id: dhan_client_id,
+        pin: pin,
+        totp_secret: totp_secret
+      )
+
+      @token_manager.generate!
+    end
+
     private
 
     # Calculates exponential backoff time

data/lib/DhanHQ/configuration.rb

@@ -98,8 +98,8 @@ module DhanHQ
     #   config.client_id = "your_client_id"
     #   config.access_token = "your_access_token"
     def initialize
-      @client_id = ENV.fetch("CLIENT_ID", nil)
-      @access_token = ENV.fetch("ACCESS_TOKEN", nil)
+      @client_id = ENV.fetch("DHAN_CLIENT_ID", nil)
+      @access_token = ENV.fetch("DHAN_ACCESS_TOKEN", nil)
       @base_url       = ENV.fetch("DHAN_BASE_URL", "https://api.dhan.co/v2")
       @ws_version     = ENV.fetch("DHAN_WS_VERSION", 2).to_i
       @ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", "wss://api-order-update.dhan.co")

data/lib/DhanHQ/contracts/order_contract.rb

@@ -75,28 +75,5 @@ module DhanHQ
         end
       end
     end
-
-    # Contract enforcing additional requirements for new order placement.
-    class PlaceOrderContract < OrderContract
-      # Additional placement specific rules
-      rule(:after_market_order) do
-        key.failure("amo_time required for after market orders") if value == true && !values[:amo_time]
-      end
-    end
-
-    # Contract extending {OrderContract} for order modification payloads.
-    class ModifyOrderContract < OrderContract
-      # Modification specific requirements
-      params do
-        required(:order_id).filled(:string)
-        optional(:quantity).maybe(:integer, gt?: 0)
-      end
-
-      rule do
-        if !values[:price] && !values[:quantity] && !values[:trigger_price]
-          key.failure("at least one modification field required")
-        end
-      end
-    end
   end
 end

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/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

@@ -48,6 +48,28 @@ module DhanHQ
 
           find(response["alertId"])
         end
+
+        ##
+        # Modify an existing conditional trigger/alert order.
+        #
+        # @param alert_id [String] The alert ID to modify
+        # @param params [Hash] Updated parameters (condition, orders, etc.)
+        #
+        # @return [AlertOrder, nil] Updated AlertOrder instance, or nil on failure
+        #
+        # @example Modify an alert order's condition
+        #   updated = DhanHQ::Models::AlertOrder.modify("12345",
+        #     condition: { comparing_value: 300 },
+        #     orders: [{ quantity: 20 }]
+        #   )
+        #
+        def modify(alert_id, params)
+          normalized = snake_case(params)
+          response = resource.update(alert_id, camelize_keys(normalized))
+          return nil unless success_response?(response)
+
+          find(alert_id)
+        end
       end
 
       def id

data/lib/DhanHQ/models/edis.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Model for EDIS (Electronic Delivery Instruction Slip) operations.
+    #
+    # EDIS is used for selling holdings from your demat account. The API provides
+    # endpoints to generate T-PIN, create eDIS forms, and check authorization status.
+    #
+    # @example Generate T-PIN
+    #   DhanHQ::Models::Edis.generate_tpin
+    #
+    # @example Generate eDIS form
+    #   response = DhanHQ::Models::Edis.generate_form(
+    #     isin: "INE155A01022",
+    #     qty: 10,
+    #     exchange: "NSE",
+    #     segment: "E",
+    #     bulk: false
+    #   )
+    #
+    # @example Check EDIS status for a security
+    #   status = DhanHQ::Models::Edis.inquire(isin: "INE155A01022")
+    #
+    class Edis < BaseModel
+      HTTP_PATH = "/edis"
+
+      class << self
+        ##
+        # Provides a shared instance of the Edis resource.
+        #
+        # @return [DhanHQ::Resources::Edis] The Edis resource client instance
+        def resource
+          @resource ||= DhanHQ::Resources::Edis.new
+        end
+
+        ##
+        # Generate T-PIN for eDIS authorization.
+        #
+        # Triggers T-PIN generation which is sent to the user's registered mobile/email.
+        #
+        # @return [Hash] API response
+        #
+        # @example Generate T-PIN before selling holdings
+        #   DhanHQ::Models::Edis.generate_tpin
+        #
+        def generate_tpin
+          resource.tpin
+        end
+
+        ##
+        # Generate an eDIS form for authorizing sale of holdings.
+        #
+        # @param isin [String] ISIN of the security (e.g., "INE155A01022")
+        # @param qty [Integer] Quantity to authorize for sale
+        # @param exchange [String] Exchange name (e.g., "NSE", "BSE")
+        # @param segment [String] Segment identifier (e.g., "E")
+        # @param bulk [Boolean] Whether this is a bulk authorization (default: false)
+        #
+        # @return [Hash] API response containing the eDIS form data
+        #
+        # @example Authorize sale of 10 shares
+        #   DhanHQ::Models::Edis.generate_form(
+        #     isin: "INE155A01022",
+        #     qty: 10,
+        #     exchange: "NSE",
+        #     segment: "E"
+        #   )
+        #
+        def generate_form(isin:, qty:, exchange:, segment:, bulk: false)
+          resource.form({ isin: isin, qty: qty, exchange: exchange, segment: segment, bulk: bulk })
+        end
+
+        ##
+        # Generate a bulk eDIS form for multiple securities.
+        #
+        # @param params [Hash] Bulk form parameters
+        # @return [Hash] API response
+        #
+        def generate_bulk_form(params)
+          resource.bulk_form(params)
+        end
+
+        ##
+        # Check EDIS authorization status for a security.
+        #
+        # @param isin [String] ISIN of the security to check
+        #
+        # @return [Hash] API response containing authorization status
+        #
+        # @example Check if EDIS is authorized
+        #   status = DhanHQ::Models::Edis.inquire(isin: "INE155A01022")
+        #
+        def inquire(isin:)
+          resource.inquire(isin)
+        end
+      end
+
+      ##
+      # No validation contract needed — EDIS operations are simple API calls.
+      #
+      # @return [nil]
+      # @api private
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/kill_switch.rb

@@ -132,6 +132,28 @@ module DhanHQ
         def deactivate
           update("DEACTIVATE")
         end
+
+        ##
+        # Fetches the current kill switch status for your account.
+        #
+        # Checks whether the kill switch is currently active or inactive for
+        # the current trading day.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing kill switch status.
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:kill_switch_status** [String] Current status: "ACTIVATE" or "DEACTIVATE"
+        #
+        # @example Check if kill switch is active
+        #   response = DhanHQ::Models::KillSwitch.status
+        #   if response[:kill_switch_status] == "ACTIVATE"
+        #     puts "Kill switch is active — trading disabled"
+        #   else
+        #     puts "Kill switch is inactive — trading enabled"
+        #   end
+        #
+        def status
+          resource.status
+        end
       end
 
       ##

data/lib/DhanHQ/models/margin.rb

@@ -139,6 +139,55 @@ module DhanHQ
           response = resource.calculate(formatted_params)
           new(response, skip_validation: true)
         end
+
+        ##
+        # Calculates margin requirements for multiple scripts in a single request.
+        #
+        # Provides combined margin calculation including hedge benefit across multiple
+        # instruments. Useful for portfolio-level margin analysis.
+        #
+        # @param params [Hash{Symbol => Object}] Request parameters
+        #   @option params [Boolean] :include_position Whether to include existing positions
+        #   @option params [Boolean] :include_order Whether to include existing orders
+        #   @option params [String] :dhan_client_id User-specific identification
+        #   @option params [Array<Hash>] :scrip_list Array of instrument margin params, each with:
+        #     - :exchange_segment [String]
+        #     - :transaction_type [String]
+        #     - :quantity [Integer]
+        #     - :product_type [String]
+        #     - :security_id [String]
+        #     - :price [Float]
+        #     - :trigger_price [Float] (optional)
+        #
+        # @return [Hash{Symbol => String}] Response hash containing:
+        #   - **:total_margin** [String] Total margin required
+        #   - **:span_margin** [String] SPAN margin
+        #   - **:exposure_margin** [String] Exposure margin
+        #   - **:equity_margin** [String] Equity margin
+        #   - **:fo_margin** [String] F&O margin
+        #   - **:commodity_margin** [String] Commodity margin
+        #   - **:currency** [String] Currency (e.g., "INR")
+        #   - **:hedge_benefit** [String] Hedge benefit amount
+        #
+        # @example Calculate margin for multiple scripts
+        #   result = DhanHQ::Models::Margin.calculate_multi(
+        #     include_position: true,
+        #     include_order: true,
+        #     dhan_client_id: "1000000132",
+        #     scrip_list: [
+        #       { exchange_segment: "NSE_EQ", transaction_type: "BUY",
+        #         quantity: 100, product_type: "CNC", security_id: "1333", price: 1428.0 },
+        #       { exchange_segment: "NSE_FNO", transaction_type: "SELL",
+        #         quantity: 50, product_type: "INTRADAY", security_id: "43492", price: 200.0 }
+        #     ]
+        #   )
+        #   puts "Total margin: #{result[:total_margin]}"
+        #   puts "Hedge benefit: #{result[:hedge_benefit]}"
+        #
+        def calculate_multi(params)
+          formatted_params = camelize_keys(params)
+          resource.calculate_multi(formatted_params)
+        end
       end
 
       ##