DhanHQ 2.1.0

data/lib/DhanHQ/contracts/slice_order_contract.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "base_contract"
+
+module DhanHQ
+  module Contracts
+    # Validation contract for slicing an order into multiple parts for Dhanhq's API.
+    #
+    # This contract ensures all required parameters are provided and optional parameters
+    # meet the required constraints when they are specified. It validates:
+    # - Required fields for slicing orders.
+    # - Conditional logic for fields based on the provided values.
+    # - Constraints such as inclusion, numerical ranges, and string formats.
+    #
+    # Example usage:
+    #   contract = Dhanhq::Contracts::SliceOrderContract.new
+    #   result = contract.call(
+    #     dhanClientId: "123456",
+    #     transactionType: "BUY",
+    #     exchangeSegment: "NSE_EQ",
+    #     productType: "CNC",
+    #     orderType: "LIMIT",
+    #     validity: "DAY",
+    #     securityId: "1001",
+    #     quantity: 10
+    #   )
+    #   result.success? # => true or false
+    #
+    # @see https://dhanhq.co/docs/v2/ Dhanhq API Documentation
+    class SliceOrderContract < BaseContract
+      # Parameters and validation rules for the slicing order request.
+      #
+      # @!attribute [r] correlationId
+      #   @return [String] Optional. Identifier for tracking, max length 25 characters.
+      # @!attribute [r] transactionType
+      #   @return [String] Required. BUY or SELL.
+      # @!attribute [r] exchangeSegment
+      #   @return [String] Required. The segment in which the order is placed.
+      #     Must be one of: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM.
+      # @!attribute [r] productType
+      #   @return [String] Required. Product type for the order.
+      #     Must be one of: CNC, INTRADAY, MARGIN, MTF, CO, BO.
+      # @!attribute [r] orderType
+      #   @return [String] Required. Type of order.
+      #     Must be one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_MARKET.
+      # @!attribute [r] validity
+      #   @return [String] Required. Validity of the order.
+      #     Must be one of: DAY, IOC, GTC, GTD.
+      # @!attribute [r] securityId
+      #   @return [String] Required. Security identifier for the order.
+      # @!attribute [r] quantity
+      #   @return [Integer] Required. Quantity of the order, must be greater than 0.
+      # @!attribute [r] disclosedQuantity
+      #   @return [Integer] Optional. Disclosed quantity, must be >= 0 if provided.
+      # @!attribute [r] price
+      #   @return [Float] Optional. Price for the order, must be > 0 if provided.
+      # @!attribute [r] triggerPrice
+      #   @return [Float] Optional. Trigger price for stop-loss orders, must be > 0 if provided.
+      # @!attribute [r] afterMarketOrder
+      #   @return [Boolean] Optional. Indicates if this is an after-market order.
+      # @!attribute [r] amoTime
+      #   @return [String] Optional. Time for after-market orders. Must be one of: OPEN, OPEN_30, OPEN_60.
+      # @!attribute [r] boProfitValue
+      #   @return [Float] Optional. Profit value for Bracket Orders, must be > 0 if provided.
+      # @!attribute [r] boStopLossValue
+      #   @return [Float] Optional. Stop-loss value for Bracket Orders, must be > 0 if provided.
+      # @!attribute [r] drvExpiryDate
+      #   @return [String] Optional. Expiry date for derivative contracts.
+      # @!attribute [r] drvOptionType
+      #   @return [String] Optional. Option type for derivatives, must be one of: CALL, PUT, NA.
+      # @!attribute [r] drvStrikePrice
+      #   @return [Float] Optional. Strike price for options, must be > 0 if provided.
+      params do
+        optional(:correlationId).maybe(:string, max_size?: 25)
+        required(:transactionType).filled(:string, included_in?: %w[BUY SELL])
+        required(:exchangeSegment).filled(:string,
+                                          included_in?: %w[NSE_EQ NSE_FNO NSE_CURRENCY BSE_EQ BSE_FNO BSE_CURRENCY
+                                                           MCX_COMM])
+        required(:productType).filled(:string, included_in?: %w[CNC INTRADAY MARGIN MTF CO BO])
+        required(:orderType).filled(:string, included_in?: %w[LIMIT MARKET STOP_LOSS STOP_LOSS_MARKET])
+        required(:validity).filled(:string, included_in?: %w[DAY IOC GTC GTD])
+        required(:securityId).filled(:string)
+        required(:quantity).filled(:integer, gt?: 0)
+        optional(:disclosedQuantity).maybe(:integer, gteq?: 0)
+        optional(:price).maybe(:float, gt?: 0)
+        optional(:triggerPrice).maybe(:float, gt?: 0)
+        optional(:afterMarketOrder).maybe(:bool)
+        optional(:amoTime).maybe(:string, included_in?: %w[OPEN OPEN_30 OPEN_60])
+        optional(:boProfitValue).maybe(:float, gt?: 0)
+        optional(:boStopLossValue).maybe(:float, gt?: 0)
+        optional(:drvExpiryDate).maybe(:string)
+        optional(:drvOptionType).maybe(:string, included_in?: %w[CALL PUT NA])
+        optional(:drvStrikePrice).maybe(:float, gt?: 0)
+      end
+
+      # Custom validation for trigger price when the order type is STOP_LOSS or STOP_LOSS_MARKET.
+      rule(:triggerPrice, :orderType) do
+        if values[:orderType].start_with?("STOP_LOSS") && !values[:triggerPrice]
+          key(:triggerPrice).failure("is required for orderType STOP_LOSS or STOP_LOSS_MARKET")
+        end
+      end
+
+      # Custom validation for AMO time when the order is marked as after-market.
+      rule(:afterMarketOrder, :amoTime) do
+        if values[:afterMarketOrder] == true && !values[:amoTime]
+          key(:amoTime).failure("is required when afterMarketOrder is true")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/core/base_api.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Base class for all API resource classes.
+  # Delegates HTTP requests to {DhanHQ::Client} and exposes helpers shared by
+  # resource wrappers.
+  class BaseAPI
+    include DhanHQ::APIHelper
+    include DhanHQ::AttributeHelper
+
+    # Default API type used when a subclass does not override {#initialize}.
+    API_TYPE = :non_trading_api
+    # Root path prepended to each endpoint segment.
+    HTTP_PATH = ""
+
+    attr_reader :client
+
+    # Initializes the BaseAPI with the appropriate Client instance
+    #
+    # @param api_type [Symbol] API type (`:order_api`, `:data_api`, `:non_trading_api`)
+    def initialize(api_type: self.class::API_TYPE)
+      @client = DhanHQ::Client.new(api_type: api_type)
+    end
+
+    # Perform a GET request via `Client`
+    #
+    # @param endpoint [String] API endpoint
+    # @param params [Hash] Query parameters
+    # @return [Hash, Array] The parsed API response
+    def get(endpoint, params: {})
+      formatted_params = format_params(endpoint, params)
+      handle_response(client.get(build_path(endpoint), formatted_params))
+    end
+
+    # Perform a POST request via `Client`
+    #
+    # @param endpoint [String] API endpoint
+    # @param params [Hash] Request body
+    # @return [Hash, Array] The parsed API response
+    def post(endpoint, params: {})
+      formatted_params = format_params(endpoint, params)
+      handle_response(client.post(build_path(endpoint), formatted_params))
+    end
+
+    # Perform a PUT request via `Client`
+    #
+    # @param endpoint [String] API endpoint
+    # @param params [Hash] Request body
+    # @return [Hash, Array] The parsed API response
+    def put(endpoint, params: {})
+      formatted_params = format_params(endpoint, params)
+      handle_response(client.put(build_path(endpoint), formatted_params))
+    end
+
+    # Perform a DELETE request via `Client`
+    #
+    # @param endpoint [String] API endpoint
+    # @return [Hash, Array] The parsed API response
+    def delete(endpoint)
+      formatted_params = format_params(endpoint, {})
+      handle_response(client.delete(build_path(endpoint), formatted_params))
+    end
+
+    private
+
+    # Performs an API request.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param endpoint [String] API endpoint
+    # @param params [Hash] Request parameters
+    # @return [Hash, Array] The parsed API response
+    # @raise [DhanHQ::Error] If an API error occurs.
+    def request(method, endpoint, params: {})
+      formatted_params = format_params(endpoint, params)
+
+      response = client.request(method, build_path(endpoint), formatted_params)
+
+      handle_response(response)
+    end
+
+    # Construct the complete API URL
+    #
+    # @param endpoint [String] API endpoint
+    # @return [String] Full API path
+    def build_path(endpoint)
+      "#{self.class::HTTP_PATH}#{endpoint}"
+    end
+
+    # Format parameters based on API endpoint
+    def format_params(endpoint, params)
+      return params if marketfeed_api?(endpoint) || params.empty?
+
+      optionchain_api?(endpoint) ? titleize_keys(params) : camelize_keys(params)
+    end
+
+    # Determines if the API endpoint is for Option Chain
+    def optionchain_api?(endpoint)
+      endpoint.include?("/optionchain")
+    end
+
+    def marketfeed_api?(endpoint)
+      endpoint.include?("/marketfeed")
+    end
+  end
+end

data/lib/DhanHQ/core/base_model.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "dry-validation"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/inflector"
+
+module DhanHQ
+  # Base class for resource objects
+  # Handles validation, attribute mapping, and response parsing
+  class BaseModel
+    # Extend & Include Modules
+    extend DhanHQ::APIHelper
+    extend DhanHQ::AttributeHelper
+    extend DhanHQ::ValidationHelper
+    extend DhanHQ::RequestHelper
+    extend DhanHQ::ResponseHelper
+
+    include DhanHQ::APIHelper
+    include DhanHQ::AttributeHelper
+    include DhanHQ::ValidationHelper
+    include DhanHQ::RequestHelper
+    include DhanHQ::ResponseHelper
+
+    # Attribute Accessors
+    attr_reader :attributes, :errors
+
+    # Initialize a new resource object
+    #
+    # @param attributes [Hash] The attributes of the resource
+    def initialize(attributes = {}, skip_validation: false)
+      @attributes = normalize_keys(attributes)
+      @errors = {}
+
+      validate! unless skip_validation
+      assign_attributes
+    end
+
+    # Class Methods
+    # Attributes set by child classes
+    class << self
+      attr_reader :defined_attributes
+
+      # Registers the set of attributes for this model
+      #
+      # @param args [Array<Symbol, String>] A list of attribute names
+      def attributes(*args)
+        @defined_attributes ||= []
+        @defined_attributes.concat(args.map(&:to_s))
+      end
+
+      # Provide a default API type, can be overridden by child classes
+      #
+      # e.g., def self.api_type; :data_api; end
+      #
+      # or override the `api` method entirely
+      def api_type
+        :order_api
+      end
+
+      # Provide a shared BaseAPI instance for this model
+      #
+      # For child classes, override `api_type` or `api` if needed
+      def api
+        @api ||= BaseAPI.new(api_type: api_type)
+      end
+
+      ##
+      # Returns the API resource used by collection methods.
+      #
+      # Subclasses may override this to return a specialized API class.
+      # By default it simply returns {#api}.
+      def resource
+        api
+      end
+
+      # Retrieve the resource path for the API
+      #
+      # @return [String] The resource path
+      def resource_path
+        self::HTTP_PATH
+      end
+
+      # Every model must either override this or set a Dry::Validation contract if they need validation
+      #
+      # @return [Dry::Validation::Contract] The validation contract
+      def validation_contract
+        raise NotImplementedError, "#{name} must implement `validation_contract`"
+      end
+
+      # Validate attributes before creating a new instance
+      def validate_attributes(attributes)
+        contract = validation_contract
+        result = contract.call(attributes)
+
+        raise ArgumentError, "Validation failed: #{result.errors.to_h}" if result.failure?
+      end
+
+      # == CRUD / Collection Methods
+
+      # Find all resources
+      #
+      # @return [Array<DhanHQ::BaseModel>, DhanHQ::ErrorObject] An array of resources or error object
+      def all
+        response = resource.get("")
+
+        parse_collection_response(response)
+      end
+
+      # Find a resource by ID
+      #
+      # @param id [String] The ID of the resource
+      # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject] The resource or error object
+      def find(id)
+        response = resource.get("/#{id}")
+
+        payload = response.is_a?(Array) ? response.first : response
+        build_from_response(payload)
+      end
+
+      # Fetches records filtered by query parameters.
+      #
+      # @param params [Hash] Query parameters supported by the API.
+      # @return [Array<BaseModel>, BaseModel, DhanHQ::ErrorObject]
+      def where(params)
+        response = resource.get("", params: params)
+        build_from_response(response)
+      end
+
+      # Create a new resource
+      #
+      # @param attributes [Hash] The attributes of the resource
+      # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject] The resource or error object
+      def create(attributes)
+        # validate_params!(attributes, validation_contract)
+
+        response = resource.post("", params: attributes)
+        build_from_response(response)
+      end
+
+      # Helper method to parse a collection response into model instances
+      #
+      # @param response [Object] The raw response from the API
+      # @return [Array<BaseModel>]
+      def parse_collection_response(response)
+        # Some endpoints return arrays, others might return a `[:data]` structure
+        return [] unless response.is_a?(Array) || (response.is_a?(Hash) && response[:data].is_a?(Array))
+
+        collection = response.is_a?(Array) ? response : response[:data]
+        collection.map { |record| new(record) }
+      end
+    end
+
+    # Instance Methods
+
+    # Update an existing resource
+    #
+    # @param attributes [Hash] Attributes to update
+    # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject]
+    def update(attributes = {})
+      response = self.class.resource.put("/#{id}", params: attributes)
+
+      success_response?(response) ? self.class.build_from_response(response) : DhanHQ::ErrorObject.new(response)
+    end
+
+    # Persists the current resource by delegating to {#create} or {#update}.
+    #
+    # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject, false]
+    def save
+      new_record? ? self.class.create(attributes) : update(attributes)
+    end
+
+    # Same as {#save} but raises {DhanHQ::Error} when persistence fails.
+    #
+    # @return [DhanHQ::BaseModel]
+    # @raise [DhanHQ::Error] When the record cannot be saved.
+    def save!
+      result = save
+      return result unless result == false || result.nil? || result.is_a?(DhanHQ::ErrorObject)
+
+      error_details =
+        if result.is_a?(DhanHQ::ErrorObject)
+          result.errors
+        elsif @errors && !@errors.empty?
+          @errors
+        else
+          "Unknown error"
+        end
+
+      raise DhanHQ::Error, "Failed to save the record: #{error_details}"
+    end
+
+    # Delete the resource
+    #
+    # @return [Boolean] True if deletion was successful
+    # Deletes the resource from the remote API.
+    #
+    # @return [Boolean] True when the server confirms deletion.
+    def delete
+      response = self.class.resource.delete("/#{id}")
+      success_response?(response)
+    rescue StandardError
+      false
+    end
+
+    # Alias for {#delete} maintained for ActiveModel familiarity.
+    #
+    # @return [Boolean]
+    def destroy
+      response = self.class.resource.delete("/#{id}")
+      success_response?(response)
+    rescue StandardError
+      false
+    end
+
+    def persisted?
+      !!id
+    end
+
+    def new_record?
+      !persisted?
+    end
+
+    # Format request parameters before sending to API
+    #
+    # @return [Hash] The camelCased attributes
+    def to_request_params
+      optionchain_api? ? titleize_keys(@attributes) : camelize_keys(@attributes)
+    end
+
+    # Identifier inferred from the loaded attributes.
+    #
+    # @return [String, Integer, nil]
+    def id
+      @attributes[:id] || @attributes[:order_id] || @attributes[:security_id]
+    end
+
+    # Dynamically assign attributes as methods
+    def assign_attributes
+      self.class.defined_attributes&.each do |attr|
+        instance_variable_set(:"@#{attr}", @attributes[attr])
+        define_singleton_method(attr) { instance_variable_get(:"@#{attr}") }
+        define_singleton_method(attr.to_s.camelize(:lower)) { instance_variable_get(:"@#{attr}") }
+      end
+    end
+
+    def optionchain_api?
+      self.class.name.include?("OptionChain")
+    end
+
+    # Validate attributes using contract
+    def valid?
+      contract_class = respond_to?(:validation_contract) ? validation_contract : self.class.validation_contract
+      return true unless contract_class
+
+      contract = contract_class.is_a?(Class) ? contract_class.new : contract_class
+      result = contract.call(@attributes)
+
+      if result.failure?
+        @errors = result.errors.to_h
+        return false
+      end
+
+      true
+    end
+  end
+end

data/lib/DhanHQ/core/base_resource.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Base wrapper exposing RESTful helpers used by resource classes.
+  class BaseResource < BaseAPI
+    def initialize(api_type: self.class::API_TYPE)
+      super(api_type: api_type) # rubocop:disable Style/SuperArguments
+    end
+
+    # Fetches all records for the resource.
+    #
+    # @return [Array<Hash>, Hash]
+    def all
+      get(self.class::HTTP_PATH)
+    end
+
+    # Retrieves a single resource by identifier.
+    #
+    # @param id [String, Integer]
+    # @return [Hash]
+    def find(id)
+      get("#{self.class::HTTP_PATH}/#{id}")
+    end
+
+    # Creates a new resource instance.
+    #
+    # @param params [Hash]
+    # @return [Hash]
+    def create(params)
+      post(self.class::HTTP_PATH, params: params)
+    end
+
+    # Updates an existing resource.
+    #
+    # @param id [String, Integer]
+    # @param params [Hash]
+    # @return [Hash]
+    def update(id, params)
+      put("#{self.class::HTTP_PATH}/#{id}", params: params)
+    end
+
+    # Deletes a resource by identifier.
+    #
+    # @param id [String, Integer]
+    # @return [Hash]
+    def delete(id)
+      super("#{self.class::HTTP_PATH}/#{id}")
+    end
+  end
+end

data/lib/DhanHQ/core/error_handler.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Provides a minimal shim for surfacing validation and runtime errors.
+  class ErrorHandler
+    # Normalises the exception raised for various error types.
+    #
+    # @param error [Dry::Validation::Result, StandardError]
+    # @raise [RuntimeError]
+    def self.handle(error)
+      case error
+      when Dry::Validation::Result
+        raise "Validation Error: #{error.errors.to_h}"
+      else
+        raise "Error: #{error.message}"
+      end
+    end
+  end
+end

data/lib/DhanHQ/error_object.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Wrapper class for API error responses
+  class ErrorObject
+    # @return [Hash] Raw error response
+    attr_reader :response
+
+    # Initialize a new ErrorObject
+    #
+    # @param response [Hash] Parsed API response
+    def initialize(response)
+      @response =
+        if response.is_a?(Hash)
+          response.with_indifferent_access
+        else
+          { message: response.to_s }.with_indifferent_access
+        end
+    end
+
+    # Always returns false to mimic success? interface on resources
+    #
+    # @return [Boolean]
+    def success?
+      false
+    end
+
+    # Extracts the error message from the response
+    #
+    # @return [String]
+    def message
+      response[:errorMessage] || response[:message] || response[:error] || "Unknown error"
+    end
+
+    # Error code if present
+    #
+    # @return [String, nil]
+    def code
+      response[:errorCode]
+    end
+
+    # Alias for the raw response hash
+    #
+    # @return [Hash]
+    def errors
+      response
+    end
+  end
+end

data/lib/DhanHQ/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Base error class for all DhanHQ API errors
+  class Error < StandardError; end
+
+  # Authentication and access errors
+  # DH-901
+  class InvalidAuthenticationError < Error; end
+  # DH-902
+  class InvalidAccessError < Error; end
+  # DH-903
+  class UserAccountError < Error; end
+  # DH-808
+  class AuthenticationFailedError < Error; end
+  # DH-807, DH-809
+  class InvalidTokenError < Error; end
+  # DH-810
+  class InvalidClientIDError < Error; end
+
+  # Rate limits and input validation errors
+  # DH-904, 805
+  class RateLimitError < Error; end
+  # DH-905
+  class InputExceptionError < Error; end
+  # DH-811, DH-812, DH-813, DH-814
+  class InvalidRequestError < Error; end
+
+  # Order and market data errors
+  class OrderError < Error; end
+  # Raised when the API signals an issue with the requested data payload.
+  class DataError < Error; end
+
+  # Server and network-related errors
+  # DH-908, 800
+  class InternalServerError < Error; end
+  # DH-1111
+  class NoHoldingsError < Error; end
+  # DH-909
+  class NetworkError < Error; end
+  # DH-910
+  class OtherError < Error; end
+  # 404
+  class NotFoundError < Error; end
+end

data/lib/DhanHQ/helpers/api_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Helper mixin offering response validation behaviour for API wrappers.
+  module APIHelper
+    # Ensures the response is a structured payload before returning it.
+    #
+    # @param response [Hash, Array]
+    # @return [Hash, Array]
+    # @raise [DhanHQ::Error] When an unexpected payload type is received.
+    def handle_response(response)
+      return response if response.is_a?(Array) || response.is_a?(Hash)
+
+      raise DhanHQ::Error, "Unexpected API response format"
+    end
+  end
+end