DhanHQ 2.1.0

data/lib/DhanHQ/helpers/attribute_helper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Helper methods for normalising attribute keys across API responses.
+  module AttributeHelper
+    # Convert keys from snake_case to camelCase
+    #
+    # @param hash [Hash] The hash to convert
+    # @return [Hash] The camelCased hash
+    def camelize_keys(hash)
+      hash.transform_keys { |key| key.to_s.camelize(:lower) }
+    end
+
+    # Convert keys from snake_case to TitleCase
+    #
+    # @param hash [Hash] The hash to convert
+    # @return [Hash] The TitleCased hash
+    def titleize_keys(hash)
+      hash.transform_keys { |key| key.to_s.titleize.delete(" ") }
+    end
+
+    # Convert keys from camelCase to snake_case
+    #
+    # @param hash [Hash] The hash to convert
+    # @return [Hash] The snake_cased hash
+    def snake_case(hash)
+      hash.transform_keys { |key| key.to_s.underscore.to_sym }
+    end
+
+    # Normalize attribute keys to be accessible as both snake_case and camelCase
+    #
+    # @param hash [Hash] The attributes hash
+    # @return [HashWithIndifferentAccess] The normalized attributes
+    def normalize_keys(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        string_key = key.to_s
+        result[string_key] = value
+        result[string_key.underscore] = value
+      end.with_indifferent_access
+    end
+
+    # Override `inspect` to display instance variables instead of attributes hash
+    #
+    # @return [String] Readable debug output for the object
+    def inspect
+      instance_vars = self.class.defined_attributes.map { |attr| "#{attr}: #{instance_variable_get(:"@#{attr}")}" }
+      "#<#{self.class.name} #{instance_vars.join(", ")}>"
+    end
+
+    # def format_params(path, params)
+    #   return params unless params.is_a?(Hash)
+
+    #   if optionchain_api?(path)
+    #     titleize_keys(params)
+    #   else
+    #     camelize_keys(params)
+    #   end
+    # end
+
+    # def camelize_keys(hash)
+    #   hash.transform_keys { |key| key.to_s.camelize(:lower) }
+    # end
+
+    # def titleize_keys(hash)
+    #   hash.transform_keys { |key| key.to_s.titleize.delete(" ") }
+    # end
+
+    # def optionchain_api?(path)
+    #   path.include?("/optionchain")
+    # end
+  end
+end

data/lib/DhanHQ/helpers/model_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Placeholder namespace for future model-level helpers.
+  module ModelHelper
+  end
+end

data/lib/DhanHQ/helpers/request_helper.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Helper mixin used by models and clients to assemble API requests.
+  module RequestHelper
+    # Builds a model object from API response
+    #
+    # @param response [Hash] API response
+    # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject]
+    def build_from_response(response)
+      return DhanHQ::ErrorObject.new(response) unless success_response?(response)
+
+      attributes = if response.is_a?(Hash) && response[:data].is_a?(Hash)
+                     response[:data]
+                   else
+                     response
+                   end
+
+      new(attributes, skip_validation: true)
+    end
+
+    private
+
+    # Dynamically builds headers for each request.
+    #
+    # @param path [String] The API endpoint path.
+    # @return [Hash] The request headers.
+    def build_headers(path)
+      headers = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "access-token" => DhanHQ.configuration.access_token
+      }
+
+      # Add client-id for DATA APIs
+      headers["client-id"] = DhanHQ.configuration.client_id if data_api?(path)
+
+      headers
+    end
+
+    # Determines if the API path requires a `client-id` header.
+    #
+    # @param path [String] The API endpoint path.
+    # @return [Boolean] True if the path belongs to a DATA API.
+    def data_api?(path)
+      DhanHQ::Constants::DATA_API_PATHS.include?(path)
+    end
+
+    # Prepares the request payload based on the HTTP method.
+    #
+    # @param req [Faraday::Request] The request object.
+    # @param payload [Hash] The request payload.
+    # @param method [Symbol] The HTTP method.
+    def prepare_payload(req, payload, method)
+      return if payload.nil? || payload.empty?
+
+      unless payload.is_a?(Hash)
+        raise DhanHQ::InputExceptionError,
+              "Invalid payload: Expected a Hash, got #{payload.class}"
+      end
+
+      case method
+      when :delete then req.params = {}
+      when :get then req.params = payload
+      else req.body = payload.to_json
+      end
+    end
+  end
+end

data/lib/DhanHQ/helpers/response_helper.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Helper mixin for normalising API responses and raising mapped errors.
+  module ResponseHelper
+    private
+
+    # Determines if the API response indicates success.
+    #
+    # Treat responses missing a `:status` key but containing
+    # an `orderId` or `orderStatus` as successful. This aligns with
+    # certain Dhan APIs which return only order details on success.
+    #
+    # @param response [Hash] Parsed API response
+    # @return [Boolean] True when the response signifies success
+    def success_response?(response)
+      return false unless response.is_a?(Hash)
+
+      return true if response[:status] == "success"
+      return true if response[:status].nil? && (response.key?(:orderId) || response.key?(:orderStatus))
+
+      false
+    end
+
+    # Handles the API response.
+    #
+    # @param response [Faraday::Response] The raw response object.
+    # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] The parsed response.
+    # @raise [DhanHQ::Error] If an HTTP error occurs.
+    def handle_response(response)
+      case response.status
+      when 200..299 then parse_json(response.body)
+      else handle_error(response)
+      end
+    end
+
+    # Handles standard HTTP errors.
+    #
+    # @param response [Faraday::Response] The raw response object.
+    # @raise [DhanHQ::Error] The specific error based on response status.
+    def handle_error(response)
+      body = parse_json(response.body)
+
+      error_code = body[:errorCode] || response.status.to_s
+      error_message = body[:errorMessage] || body[:message] || "Unknown error"
+      if error_code == "DH-1111"
+        error_message = "No holdings found for this account. Add holdings or wait for them to settle before retrying."
+      end
+
+      error_class = DhanHQ::Constants::DHAN_ERROR_MAPPING[error_code]
+
+      error_class ||=
+        case response.status
+        when 400 then DhanHQ::InputExceptionError
+        when 401 then DhanHQ::InvalidAuthenticationError
+        when 403 then DhanHQ::InvalidAccessError
+        when 404 then DhanHQ::NotFoundError
+        when 429 then DhanHQ::RateLimitError
+        when 500..599 then DhanHQ::InternalServerError
+        else DhanHQ::OtherError
+        end
+
+      error_text =
+        if error_code == "DH-1111"
+          "#{error_message} (error code: #{error_code})"
+        else
+          "#{error_code}: #{error_message}"
+        end
+
+      raise error_class, error_text
+    end
+
+    # Parses JSON response safely. Converts response body to a hash or array with indifferent access.
+    #
+    # @param body [String, Hash] The response body.
+    # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] The parsed JSON.
+    def parse_json(body)
+      parsed_body =
+        if body.is_a?(String)
+          begin
+            JSON.parse(body, symbolize_names: true)
+          rescue JSON::ParserError
+            {} # Return an empty hash if the string is not valid JSON
+          end
+        else
+          body
+        end
+
+      if parsed_body.is_a?(Hash)
+        parsed_body.with_indifferent_access
+      elsif parsed_body.is_a?(Array)
+        parsed_body.map(&:with_indifferent_access)
+      else
+        parsed_body
+      end
+    end
+  end
+end

data/lib/DhanHQ/helpers/validation_helper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Helper methods for running Dry::Validation contracts against payloads.
+  module ValidationHelper
+    # Validate the attributes using the validation contract
+    #
+    # @param params [Hash] The parameters to validate
+    # @param contract_class [Class] The contract class to use for validation
+    def validate_params!(params, contract_class)
+      contract = contract_class.new
+      result = contract.call(params)
+
+      raise DhanHQ::Error, "Validation Error: #{result.errors.to_h}" unless result.success?
+    end
+
+    # Validate instance attributes using the defined validation contract
+    def validate!
+      contract_class = respond_to?(:validation_contract) ? validation_contract : self.class.validation_contract
+      return unless contract_class
+
+      contract = contract_class.is_a?(Class) ? contract_class.new : contract_class
+
+      result = contract.call(@attributes)
+      @errors = result.errors.to_h unless result.success?
+      raise DhanHQ::Error, "Validation Error: #{@errors}" unless valid?
+    end
+
+    # Checks if the current instance is valid
+    #
+    # @return [Boolean] True if the model is valid
+    def valid?
+      @errors.empty?
+    end
+  end
+end

data/lib/DhanHQ/json_loader.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DhanHQ
+  # Utility for loading canned JSON fixtures bundled with the gem.
+  module JSONLoader
+    # Loads and symbolises a JSON request payload from the `requests/` folder.
+    #
+    # @param file [String] Relative path to the fixture file.
+    # @return [Hash] Parsed JSON payload with symbolised keys.
+    def self.load(file)
+      file_path = File.expand_path("requests/#{file}", __dir__)
+      JSON.parse(File.read(file_path), symbolize_names: true)
+    rescue Errno::ENOENT
+      puts "File not found: #{file_path}"
+      {}
+    rescue JSON::ParserError
+      puts "Invalid JSON format in #{file_path}"
+      {}
+    end
+  end
+end

data/lib/DhanHQ/models/edis.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model wrapper for electronic DIS flows.
+    class Edis < BaseModel
+      # Base path backing the model operations.
+      HTTP_PATH = "/v2/edis"
+
+      class << self
+        # Shared resource client used by the model helpers.
+        #
+        # @return [DhanHQ::Resources::Edis]
+        def resource
+          @resource ||= DhanHQ::Resources::Edis.new
+        end
+
+        # Submits an EDIS form request.
+        #
+        # @param params [Hash]
+        # @return [Hash]
+        def form(params)
+          resource.form(params)
+        end
+
+        # Submits a bulk EDIS form request.
+        #
+        # @param params [Hash]
+        # @return [Hash]
+        def bulk_form(params)
+          resource.bulk_form(params)
+        end
+
+        # Requests a TPIN for the configured client.
+        #
+        # @return [Hash]
+        def tpin
+          resource.tpin
+        end
+
+        # Inquires EDIS status for a specific ISIN.
+        #
+        # @param isin [String]
+        # @return [Hash]
+        def inquire(isin)
+          resource.inquire(isin)
+        end
+      end
+
+      # EDIS payloads are validated upstream so no contract is applied.
+      #
+      # @return [nil]
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/forever_order.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # ActiveModel-style wrapper for Good Till Trigger/Forever orders.
+    class ForeverOrder < BaseModel
+      attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
+                 :transaction_type, :exchange_segment, :product_type, :order_flag,
+                 :order_type, :validity, :trading_symbol, :security_id, :quantity,
+                 :disclosed_quantity, :price, :trigger_price, :price1,
+                 :trigger_price1, :quantity1, :leg_name, :create_time,
+                 :update_time, :exchange_time, :drv_expiry_date, :drv_option_type,
+                 :drv_strike_price
+
+      class << self
+        # Provides a shared instance of the ForeverOrders resource
+        #
+        # @return [DhanHQ::Resources::ForeverOrders]
+        def resource
+          @resource ||= DhanHQ::Resources::ForeverOrders.new
+        end
+
+        ##
+        # Fetch all forever orders
+        #
+        # @return [Array<ForeverOrder>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |o| new(o, skip_validation: true) }
+        end
+
+        ##
+        # Retrieve a specific forever order
+        #
+        # @param order_id [String]
+        # @return [ForeverOrder, nil]
+        def find(order_id)
+          response = resource.find(order_id)
+          return nil unless response.is_a?(Hash) && response.any?
+
+          new(response, skip_validation: true)
+        end
+
+        ##
+        # Create a new forever order
+        #
+        # @param params [Hash]
+        # @return [ForeverOrder, nil]
+        def create(params)
+          response = resource.create(params)
+          return nil unless response.is_a?(Hash) && response["orderId"]
+
+          find(response["orderId"])
+        end
+      end
+
+      ##
+      # Modify an existing forever order
+      #
+      # @param new_params [Hash]
+      # @return [ForeverOrder, nil]
+      def modify(new_params)
+        raise "Order ID is required to modify a forever order" unless id
+
+        response = self.class.resource.update(id, new_params)
+        return self.class.find(id) if self.class.send(:success_response?, response)
+
+        nil
+      end
+
+      ##
+      # Cancel the forever order
+      #
+      # @return [Boolean]
+      def cancel
+        raise "Order ID is required to cancel a forever order" unless id
+
+        response = self.class.resource.cancel(id)
+        response["orderStatus"] == "CANCELLED"
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/funds.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model representing the funds/limits endpoint response.
+    class Funds < BaseModel
+      # Base path used by the funds resource.
+      HTTP_PATH = "/v2/fundlimit"
+
+      attributes :available_balance, :sod_limit, :collateral_amount, :receiveable_amount, :utilized_amount,
+                 :blocked_payout_amount, :withdrawable_balance
+
+      # The API currently returns the key `availabelBalance` (note the typo).
+      # To maintain backwards compatibility while exposing a correctly
+      # spelled attribute, map the API response to `available_balance`.
+      def assign_attributes
+        if @attributes.key?(:availabel_balance) && !@attributes.key?(:available_balance)
+          @attributes[:available_balance] = @attributes[:availabel_balance]
+        end
+        super
+      end
+      class << self
+        ##
+        # Provides a **shared instance** of the `Funds` resource.
+        #
+        # @return [DhanHQ::Resources::Funds]
+        def resource
+          @resource ||= DhanHQ::Resources::Funds.new
+        end
+
+        ##
+        # Fetch fund details.
+        #
+        # @return [Fund]
+        def fetch
+          response = resource.fetch
+          new(response, skip_validation: true)
+        end
+
+        ##
+        # Fetch only the available balance.
+        #
+        # @return [Float] Available balance in the trading account.
+        def balance
+          fetch.available_balance
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/historical_data.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Model class for fetching Daily & Intraday data
+    # The default response is a Hash with arrays of "open", "high", "low", etc.
+    #
+    class HistoricalData < BaseModel
+      # Typically, we won't define a single resource path,
+      # because we call "daily" or "intraday" endpoints specifically.
+      # So let's rely on the resource call directly.
+      HTTP_PATH = "/v2/charts"
+
+      # If you want typed attributes, you could define them,
+      # but the endpoints return arrays. We'll keep it raw.
+      # e.g. attributes :open, :high, :low, :close, :volume, :timestamp
+
+      class << self
+        ##
+        # Provide a **shared instance** of the `HistoricalData` resource
+        #
+        # @return [DhanHQ::Resources::HistoricalData]
+        def resource
+          @resource ||= DhanHQ::Resources::HistoricalData.new
+        end
+
+        ##
+        # Daily historical data
+        # @param params [Hash] The request parameters, e.g.:
+        #   {
+        #     security_id: "1333",
+        #     exchange_segment: "NSE_EQ",
+        #     instrument: "EQUITY",
+        #     expiry_code: 0,
+        #     from_date: "2022-01-08",
+        #     to_date: "2022-02-08"
+        #   }
+        # @return [HashWithIndifferentAccess]
+        #   {
+        #     open: [...], high: [...], low: [...], close: [...],
+        #     volume: [...], timestamp: [...]
+        #   }
+        def daily(params)
+          validate_params!(params, DhanHQ::Contracts::HistoricalDataContract)
+          # You can rename the keys from snake_case to something if needed
+          resource.daily(params)
+          # return as a raw hash or transform further
+        end
+
+        ##
+        # Intraday historical data
+        # @param params [Hash], e.g.:
+        #   {
+        #     security_id: "1333",
+        #     exchange_segment: "NSE_EQ",
+        #     instrument: "EQUITY",
+        #     interval: "15",
+        #     from_date: "2024-09-11",
+        #     to_date: "2024-09-15"
+        #   }
+        # @return [HashWithIndifferentAccess]
+        #   { open: [...], high: [...], low: [...], close: [...],
+        #     volume: [...], timestamp: [...] }
+        def intraday(params)
+          validate_params!(params, DhanHQ::Contracts::HistoricalDataContract)
+          resource.intraday(params)
+        end
+      end
+
+      # For a read-only type of data, we might skip validations or specify a contract if needed
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/holding.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model representing a single portfolio holding.
+    class Holding < BaseModel
+      # Base path used when retrieving holdings.
+      HTTP_PATH = "/v2/holdings"
+
+      attributes :exchange, :trading_symbol, :security_id, :isin, :total_qty,
+                 :dp_qty, :t1_qty, :available_qty, :collateral_qty, :avg_cost_price
+
+      class << self
+        ##
+        # Provides a **shared instance** of the `Holdings` resource.
+        #
+        # @return [DhanHQ::Resources::Holdings]
+        def resource
+          @resource ||= DhanHQ::Resources::Holdings.new
+        end
+
+        ##
+        # Fetch all holdings.
+        #
+        # @return [Array<Holding>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |holding| new(holding, skip_validation: true) }
+        rescue DhanHQ::NoHoldingsError
+          []
+        end
+      end
+
+      ##
+      # Convert model attributes to a hash.
+      #
+      # @return [Hash] Hash representation of the Holding model.
+      def to_h
+        {
+          exchange: exchange,
+          trading_symbol: trading_symbol,
+          security_id: security_id,
+          isin: isin,
+          total_qty: total_qty,
+          dp_qty: dp_qty,
+          t1_qty: t1_qty,
+          available_qty: available_qty,
+          collateral_qty: collateral_qty,
+          avg_cost_price: avg_cost_price
+        }
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/kill_switch.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model helper to toggle the trading kill switch.
+    class KillSwitch < BaseModel
+      # Base path used by the kill switch resource.
+      HTTP_PATH = "/v2/killswitch"
+
+      class << self
+        # Shared resource for kill switch operations.
+        #
+        # @return [DhanHQ::Resources::KillSwitch]
+        def resource
+          @resource ||= DhanHQ::Resources::KillSwitch.new
+        end
+
+        # Updates the kill switch status.
+        #
+        # @param status [String]
+        # @return [Hash]
+        def update(status)
+          resource.update(kill_switch_status: status)
+        end
+
+        # Activates the kill switch for the account.
+        #
+        # @return [Hash]
+        def activate
+          update("ACTIVATE")
+        end
+
+        # Deactivates the kill switch for the account.
+        #
+        # @return [Hash]
+        def deactivate
+          update("DEACTIVATE")
+        end
+      end
+
+      # No explicit validation contract is required for kill switch updates.
+      #
+      # @return [nil]
+      def validation_contract
+        nil
+      end
+    end
+  end
+end