DhanHQ 2.1.0

data/lib/DhanHQ/models/ledger_entry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Represents a single row/entry in the Ledger.
+    # Ledger data typically returns an array of these objects.
+    class LedgerEntry < BaseModel
+      # The endpoint is /v2/ledger?from-date=...&to-date=...
+      # So we may define a resource path or rely on the Statements resource.
+      HTTP_PATH = "/v2/ledger"
+
+      # Typical fields from API docs
+      attributes :dhan_client_id, :narration, :voucherdate, :exchange,
+                 :voucherdesc, :vouchernumber, :debit, :credit, :runbal
+
+      class << self
+        ##
+        # Provides a **shared instance** of the `Statements` resource.
+        #
+        # @return [DhanHQ::Resources::Statements]
+        def resource
+          @resource ||= DhanHQ::Resources::Statements.new
+        end
+
+        ##
+        # Fetch ledger entries for the given date range.
+        #
+        # @param from_date [String] e.g. "2023-01-01"
+        # @param to_date   [String] e.g. "2023-01-31"
+        # @return [Array<LedgerEntry>]
+        def all(from_date:, to_date:)
+          # The resource call returns an Array<Hash>, according to the docs.
+          response = resource.ledger(from_date: from_date, to_date: to_date)
+
+          return [] unless response.is_a?(Array)
+
+          response.map do |entry|
+            new(entry, skip_validation: true)
+          end
+        end
+      end
+
+      # Optional: you can override #to_h or #inspect if you want a custom representation
+      def to_h
+        {
+          dhan_client_id: dhan_client_id,
+          narration: narration,
+          voucherdate: voucherdate,
+          exchange: exchange,
+          voucherdesc: voucherdesc,
+          vouchernumber: vouchernumber,
+          debit: debit,
+          credit: credit,
+          runbal: runbal
+        }
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/margin.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model for the on-demand margin calculator response.
+    class Margin < BaseModel
+      # Base path used to invoke the calculator.
+      HTTP_PATH = "/v2/margincalculator"
+
+      attr_reader :total_margin, :span_margin, :exposure_margin, :available_balance,
+                  :variable_margin, :insufficient_balance, :brokerage, :leverage
+
+      class << self
+        ##
+        # Provides a **shared instance** of the `MarginCalculator` resource.
+        #
+        # @return [DhanHQ::Resources::MarginCalculator]
+        def resource
+          @resource ||= DhanHQ::Resources::MarginCalculator.new
+        end
+
+        ##
+        # Calculate margin requirements for an order.
+        #
+        # @param params [Hash] Request parameters for margin calculation.
+        # @return [Margin]
+        def calculate(params)
+          formatted_params = camelize_keys(params)
+          validate_params!(formatted_params, DhanHQ::Contracts::MarginCalculatorContract)
+
+          response = resource.calculate(formatted_params)
+          new(response, skip_validation: true)
+        end
+      end
+
+      ##
+      # Convert model attributes to a hash.
+      #
+      # @return [Hash] Hash representation of the Margin model.
+      def to_h
+        {
+          total_margin: total_margin,
+          span_margin: span_margin,
+          exposure_margin: exposure_margin,
+          available_balance: available_balance,
+          variable_margin: variable_margin,
+          insufficient_balance: insufficient_balance,
+          brokerage: brokerage,
+          leverage: leverage
+        }
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/market_feed.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Lightweight wrapper exposing market feed resources.
+    class MarketFeed < BaseModel
+      class << self
+        # Fetches last traded price snapshots.
+        #
+        # @param params [Hash]
+        # @return [Hash]
+        def ltp(params)
+          resource.ltp(params)
+        end
+
+        # Fetches OHLC data for the requested instruments.
+        #
+        # @param params [Hash]
+        # @return [Hash]
+        def ohlc(params)
+          resource.ohlc(params)
+        end
+
+        # Fetches full quote depth and analytics.
+        #
+        # @param params [Hash]
+        # @return [Hash]
+        def quote(params)
+          resource.quote(params)
+        end
+
+        # Shared market feed resource instance.
+        #
+        # @return [DhanHQ::Resources::MarketFeed]
+        def resource
+          @resource ||= DhanHQ::Resources::MarketFeed.new
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/option_chain.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../contracts/option_chain_contract"
+
+module DhanHQ
+  module Models
+    # Model for fetching and filtering option chain snapshots.
+    class OptionChain < BaseModel
+      attr_reader :underlying_scrip, :underlying_seg, :expiry, :last_price, :option_data
+
+      class << self
+        # Shared resource for option chain operations.
+        #
+        # @return [DhanHQ::Resources::OptionChain]
+        def resource
+          @resource ||= DhanHQ::Resources::OptionChain.new
+        end
+
+        # Fetch the entire option chain for an instrument
+        #
+        # @param params [Hash] The request parameters (snake_case format)
+        # @return [HashWithIndifferentAccess] The filtered option chain data
+        def fetch(params)
+          validate_params!(params, DhanHQ::Contracts::OptionChainContract)
+
+          response = resource.fetch(params)
+          return {}.with_indifferent_access unless response[:status] == "success"
+
+          filter_valid_strikes(response[:data]).with_indifferent_access
+        end
+
+        # Fetch the expiry list of an underlying security
+        #
+        # @param params [Hash] The request parameters (snake_case format)
+        # @return [Array<String>] The list of expiry dates
+        def fetch_expiry_list(params)
+          response = resource.expirylist(params)
+          response[:status] == "success" ? response[:data] : []
+        end
+
+        private
+
+        # **Filters valid strikes where `ce` or `pe` has `last_price > 0` and keeps strike prices as-is**
+        #
+        # @param data [Hash] The API response data
+        # @return [Hash] The filtered option chain data with original strike price keys
+        def filter_valid_strikes(data)
+          return {} unless data.is_a?(Hash) && data.key?(:oc)
+
+          filtered_oc = data[:oc].each_with_object({}) do |(strike_price, strike_data), result|
+            ce_last_price = strike_data.dig("ce", "last_price").to_f
+            pe_last_price = strike_data.dig("pe", "last_price").to_f
+
+            # Only keep strikes where at least one of CE or PE has a valid last_price
+            result[strike_price] = strike_data if ce_last_price.positive? || pe_last_price.positive?
+          end
+
+          data.merge(oc: filtered_oc)
+        end
+
+        # Validation contract for option chain
+        #
+        # @return [DhanHQ::Contracts::OptionChainContract]
+        def validation_contract
+          DhanHQ::Contracts::OptionChainContract.new
+        end
+      end
+
+      private
+
+      # Validation contract for option chain
+      #
+      # @return [DhanHQ::Contracts::OptionChainContract]
+      def validation_contract
+        DhanHQ::Contracts::OptionChainContract.new
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/order.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative "../contracts/place_order_contract"
+require_relative "../contracts/modify_order_contract"
+
+module DhanHQ
+  # ActiveRecord-style models built on top of the REST resources.
+  module Models
+    # Representation of an order as returned by the REST APIs.
+    class Order < BaseModel
+      # Attributes eligible for modification requests.
+      MODIFIABLE_FIELDS = %i[
+        dhan_client_id
+        order_id
+        order_type
+        quantity
+        price
+        trigger_price
+        disclosed_quantity
+        validity
+        leg_name
+      ].freeze
+
+      attr_reader :order_id, :order_status
+
+      # Define attributes that are part of an order
+      attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
+                 :transaction_type, :exchange_segment, :product_type, :order_type,
+                 :validity, :trading_symbol, :security_id, :quantity,
+                 :disclosed_quantity, :price, :trigger_price, :after_market_order,
+                 :bo_profit_value, :bo_stop_loss_value, :leg_name, :create_time,
+                 :update_time, :exchange_time, :drv_expiry_date, :drv_option_type,
+                 :drv_strike_price, :oms_error_code, :oms_error_description, :algo_id,
+                 :remaining_quantity, :average_traded_price, :filled_qty
+
+      class << self
+        ##
+        # Provides a **shared instance** of the `Orders` resource
+        #
+        # @return [DhanHQ::Resources::Orders]
+        def resource
+          @resource ||= DhanHQ::Resources::Orders.new
+        end
+
+        ##
+        # Fetch all orders for the day.
+        #
+        # @return [Array<Order>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |order| new(order, skip_validation: true) }
+        end
+
+        ##
+        # Fetch a specific order by ID.
+        #
+        # @param order_id [String]
+        # @return [Order, nil]
+        def find(order_id)
+          response = resource.find(order_id)
+          return nil unless response.is_a?(Hash) || (response.is_a?(Array) && response.any?)
+
+          order_data = response.is_a?(Array) ? response.first : response
+          new(order_data, skip_validation: true)
+        end
+
+        ##
+        # Fetch a specific order by correlation ID.
+        #
+        # @param correlation_id [String]
+        # @return [Order, nil]
+        def find_by_correlation(correlation_id)
+          response = resource.by_correlation(correlation_id)
+          return nil unless response[:status] == "success"
+
+          new(response, skip_validation: true)
+        end
+
+        # Place a new order
+        #
+        # @param params [Hash] Order parameters
+        # @return [Order]
+        def place(params)
+          normalized_params = snake_case(params)
+          validate_params!(normalized_params, DhanHQ::Contracts::PlaceOrderContract)
+
+          response = resource.create(camelize_keys(normalized_params))
+          return nil unless response.is_a?(Hash) && response["orderId"]
+
+          # Fetch the complete order details
+          find(response["orderId"])
+        end
+
+        ##
+        # AR-like create: new => valid? => save => resource.create
+        # But we can also define a class method if we want direct:
+        #   Order.create(order_params)
+        #
+        # For the typical usage "Order.new(...).save", we rely on #save below.
+        def create(params)
+          order = new(params) # build it
+          return order unless order.valid? # run place order contract?
+
+          order.save # calls resource create or update
+          order
+        end
+      end
+
+      # Modify the order while preserving existing attributes
+      #
+      # @param new_params [Hash]
+      # @return [Order, nil]
+      def modify(new_params)
+        raise "Order ID is required to modify an order" unless id
+
+        base_payload = attributes.merge(new_params)
+        normalized_payload = snake_case(base_payload).merge(order_id: id)
+        filtered_payload = normalized_payload.each_with_object({}) do |(key, value), memo|
+          symbolized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          memo[symbolized_key] = value if MODIFIABLE_FIELDS.include?(symbolized_key)
+        end
+        filtered_payload[:order_id] ||= id
+        filtered_payload[:dhan_client_id] ||= attributes[:dhan_client_id]
+
+        cleaned_payload = filtered_payload.compact
+        formatted_payload = camelize_keys(cleaned_payload)
+        validate_params!(formatted_payload, DhanHQ::Contracts::ModifyOrderContract)
+
+        response = self.class.resource.update(id, formatted_payload)
+        response = response.with_indifferent_access if response.respond_to?(:with_indifferent_access)
+
+        return DhanHQ::ErrorObject.new(response) unless success_response?(response)
+
+        @attributes.merge!(normalize_keys(response))
+        assign_attributes
+        self
+      end
+
+      # Cancel the order
+      #
+      # @return [Boolean]
+      def cancel
+        raise "Order ID is required to cancel an order" unless id
+
+        response = self.class.resource.cancel(id)
+        response["orderStatus"] == "CANCELLED"
+      end
+
+      # Fetch the latest details of the order
+      #
+      # @return [Order, nil]
+      def refresh
+        raise "Order ID is required to refresh an order" unless id
+
+        self.class.find(id)
+      end
+
+      ##
+      # This is how we figure out if it's an existing record or not:
+      def new_record?
+        order_id.nil? || order_id.to_s.empty?
+      end
+
+      ##
+      # The ID used for resource calls
+      def id
+        order_id
+      end
+
+      ##
+      # Save: If new_record?, do resource.create
+      # else resource.update
+      def save
+        return false unless valid?
+
+        if new_record?
+          # PLACE ORDER
+          response = self.class.resource.create(to_request_params)
+          if success_response?(response) && response["orderId"]
+            @attributes.merge!(normalize_keys(response))
+            assign_attributes
+            true
+          else
+            # maybe store errors?
+            false
+          end
+        else
+          # MODIFY ORDER
+          response = self.class.resource.update(id, to_request_params)
+          if success_response?(response) && response["orderStatus"]
+            @attributes.merge!(normalize_keys(response))
+            assign_attributes
+            true
+          else
+            false
+          end
+        end
+      end
+
+      ##
+      # Cancel => calls resource.delete
+      def destroy
+        return false if new_record?
+
+        response = self.class.resource.delete(id)
+        if success_response?(response) && response["orderStatus"] == "CANCELLED"
+          @attributes[:order_status] = "CANCELLED"
+          true
+        else
+          false
+        end
+      end
+      alias delete destroy
+
+      ##
+      # Slicing (optional)
+      # If you want an AR approach:
+      def slice_order(params)
+        raise "Order ID is required to slice an order" unless id
+
+        base_payload = params.merge(order_id: id)
+        formatted_payload = camelize_keys(base_payload)
+
+        validate_params!(formatted_payload, DhanHQ::Contracts::SliceOrderContract)
+
+        self.class.resource.slicing(formatted_payload)
+      end
+
+      ##
+      # Because we have two separate contracts: place vs. modify
+      # We can do something like:
+      def validation_contract
+        new_record? ? DhanHQ::Contracts::PlaceOrderContract.new : DhanHQ::Contracts::ModifyOrderContract.new
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/position.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model representing an intraday or carry-forward position snapshot.
+    class Position < BaseModel
+      # Base path used by the positions resource.
+      HTTP_PATH = "/v2/positions"
+
+      attributes :dhan_client_id, :trading_symbol, :security_id, :position_type, :exchange_segment,
+                 :product_type, :buy_avg, :buy_qty, :cost_price, :sell_avg, :sell_qty,
+                 :net_qty, :realized_profit, :unrealized_profit, :rbi_reference_rate, :multiplier,
+                 :carry_forward_buy_qty, :carry_forward_sell_qty, :carry_forward_buy_value,
+                 :carry_forward_sell_value, :day_buy_qty, :day_sell_qty, :day_buy_value,
+                 :day_sell_value, :drv_expiry_date, :drv_option_type, :drv_strike_price,
+                 :cross_currency
+
+      class << self
+        ##
+        # Provides a **shared instance** of the `Positions` resource.
+        #
+        # @return [DhanHQ::Resources::Positions]
+        def resource
+          @resource ||= DhanHQ::Resources::Positions.new
+        end
+
+        ##
+        # Fetch all positions for the day.
+        #
+        # @return [Array<Position>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map do |position|
+            new(snake_case(position), skip_validation: true)
+          end
+        end
+
+        # Filters the position list down to non-closed entries.
+        #
+        # @return [Array<Position>]
+        def active
+          all.reject { |position| position.position_type == "CLOSED" }
+        end
+
+        # Convert an existing position (intraday <-> delivery)
+        # @param params [Hash] parameters as required by the API
+        # @return [Hash, DhanHQ::ErrorObject]
+        def convert(params)
+          formatted_params = camelize_keys(params)
+          validate_params!(formatted_params, DhanHQ::Contracts::PositionConversionContract)
+
+          response = resource.convert(formatted_params)
+          success_response?(response) ? response : DhanHQ::ErrorObject.new(response)
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/profile.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Ruby wrapper around the `/v2/profile` endpoint. Provides typed accessors
+    # and snake_case keys while leaving the underlying response untouched.
+    class Profile < BaseModel
+      # Base path for profile retrieval.
+      HTTP_PATH = "/v2/profile"
+
+      attributes :dhan_client_id, :token_validity, :active_segment, :ddpi,
+                 :mtf, :data_plan, :data_validity
+
+      class << self
+        ##
+        # Provides a shared instance of the profile resource.
+        #
+        # @return [DhanHQ::Resources::Profile]
+        def resource
+          @resource ||= DhanHQ::Resources::Profile.new
+        end
+
+        ##
+        # Fetch the authenticated user's profile details.
+        #
+        # @return [DhanHQ::Models::Profile, nil]
+        def fetch
+          response = resource.fetch
+          return nil unless response.is_a?(Hash)
+
+          new(response, skip_validation: true)
+        end
+      end
+
+      # Profile responses are informational and not validated locally.
+      #
+      # @return [nil]
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/super_order.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Model wrapping multi-leg super order payloads.
+    class SuperOrder < BaseModel
+      attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
+                 :transaction_type, :exchange_segment, :product_type, :order_type,
+                 :validity, :trading_symbol, :security_id, :quantity,
+                 :remaining_quantity, :ltp, :price, :after_market_order,
+                 :leg_name, :exchange_order_id, :create_time, :update_time,
+                 :exchange_time, :oms_error_description, :average_traded_price,
+                 :filled_qty, :leg_details, :target_price, :stop_loss_price,
+                 :trailing_jump
+
+      class << self
+        # Shared resource instance used for API calls.
+        #
+        # @return [DhanHQ::Resources::SuperOrders]
+        def resource
+          @resource ||= DhanHQ::Resources::SuperOrders.new
+        end
+
+        # Fetches all configured super orders.
+        #
+        # @return [Array<SuperOrder>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |o| new(o, skip_validation: true) }
+        end
+
+        # Creates a new super order with the provided legs.
+        #
+        # @param params [Hash]
+        # @return [SuperOrder, nil]
+        def create(params)
+          response = resource.create(params)
+          return nil unless response.is_a?(Hash) && response["orderId"]
+
+          new(order_id: response["orderId"], order_status: response["orderStatus"], skip_validation: true)
+        end
+      end
+
+      # Updates the order legs for an existing super order.
+      #
+      # @param new_params [Hash]
+      # @return [Boolean]
+      def modify(new_params)
+        raise "Order ID is required to modify a super order" unless id
+
+        response = self.class.resource.update(id, new_params)
+        response["orderId"] == id
+      end
+
+      # Cancels a specific leg (or the entry leg by default).
+      #
+      # @param leg_name [String]
+      # @return [Boolean]
+      def cancel(leg_name = "ENTRY_LEG")
+        raise "Order ID is required to cancel a super order" unless id
+
+        response = self.class.resource.cancel(id, leg_name)
+        response["orderStatus"] == "CANCELLED"
+      end
+    end
+  end
+end