DhanHQ 2.3.0 → 2.4.0

data/lib/DhanHQ/auth/token_manager.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module DhanHQ
+  module Auth
+    # Manages automatic token lifecycle including generation, renewal, and validation.
+    #
+    # TokenManager provides production-grade token automation by:
+    # - Generating new tokens via TOTP when needed
+    # - Renewing tokens before expiry (5-minute buffer)
+    # - Falling back to full generation if renewal fails
+    # - Thread-safe token operations via Monitor lock
+    #
+    # @example Enable auto token management
+    #   client = DhanHQ::Client.new(api_type: :order_api)
+    #   client.enable_auto_token_management!(
+    #     dhan_client_id: ENV["DHAN_CLIENT_ID"],
+    #     pin: ENV["DHAN_PIN"],
+    #     totp_secret: ENV["DHAN_TOTP_SECRET"]
+    #   )
+    #
+    # @example Manual usage
+    #   manager = TokenManager.new(
+    #     dhan_client_id: "123",
+    #     pin: "1234",
+    #     totp_secret: "SECRET"
+    #   )
+    #   manager.ensure_valid_token!  # Auto-generates or renews as needed
+    #
+    # @see Auth::TokenGenerator for TOTP-based token generation
+    # @see Auth::TokenRenewal for token renewal logic
+    class TokenManager
+      def initialize(dhan_client_id:, pin:, totp_secret:)
+        @dhan_client_id = dhan_client_id
+        @pin = pin
+        @totp_secret = totp_secret
+
+        @token = nil
+        @lock = Monitor.new
+      end
+
+      def generate!
+        @lock.synchronize do
+          token = Auth::TokenGenerator.new.generate(
+            dhan_client_id: @dhan_client_id,
+            pin: @pin,
+            totp_secret: @totp_secret
+          )
+
+          apply_token(token)
+        end
+      end
+
+      def ensure_valid_token!
+        return generate! unless @token
+
+        return unless @token.needs_refresh?
+
+        refresh!
+      end
+
+      def refresh!
+        @lock.synchronize do
+          return generate! unless @token
+
+          renewal = Auth::TokenRenewal.new.renew
+          apply_token(renewal)
+        rescue Errors::AuthenticationError
+          generate!
+        end
+      end
+
+      private
+
+      def apply_token(token)
+        @token = token
+
+        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
+    end
+  end
+end

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/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/version.rb

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