DhanHQ 2.1.8 → 2.1.10

data/lib/DhanHQ/models/forever_order.rb

@@ -2,7 +2,67 @@
 
 module DhanHQ
   module Models
-    # ActiveModel-style wrapper for Good Till Trigger/Forever orders.
+    ##
+    # Model for creating and managing Forever Orders (also known as Good Till Triggered or GTT orders).
+    #
+    # Forever Orders are conditional orders that remain active until triggered, modified, or cancelled.
+    # They can be configured as:
+    # - **SINGLE**: A single order that triggers when the trigger price is reached
+    # - **OCO** (One-Cancels-Other): Two linked orders where execution of one cancels the other
+    #
+    # Order placement, modification, and cancellation APIs require Static IP whitelisting.
+    #
+    # @example Create a single forever order
+    #   order = DhanHQ::Models::ForeverOrder.create(
+    #     order_flag: "SINGLE",
+    #     transaction_type: "BUY",
+    #     exchange_segment: "NSE_EQ",
+    #     product_type: "CNC",
+    #     order_type: "LIMIT",
+    #     validity: "DAY",
+    #     security_id: "1333",
+    #     quantity: 5,
+    #     price: 1428.0,
+    #     trigger_price: 1427.0
+    #   )
+    #
+    # @example Create an OCO forever order
+    #   order = DhanHQ::Models::ForeverOrder.create(
+    #     order_flag: "OCO",
+    #     transaction_type: "BUY",
+    #     exchange_segment: "NSE_EQ",
+    #     product_type: "CNC",
+    #     order_type: "LIMIT",
+    #     validity: "DAY",
+    #     security_id: "1333",
+    #     quantity: 5,
+    #     price: 1428.0,
+    #     trigger_price: 1427.0,
+    #     price1: 1420.0,
+    #     trigger_price1: 1419.0,
+    #     quantity1: 10
+    #   )
+    #
+    # @example Modify a forever order
+    #   order = DhanHQ::Models::ForeverOrder.find("5132208051112")
+    #   order.modify(
+    #     order_flag: "SINGLE",
+    #     order_type: "LIMIT",
+    #     leg_name: "TARGET_LEG",
+    #     quantity: 15,
+    #     price: 1421.0,
+    #     trigger_price: 1420.0,
+    #     validity: "DAY"
+    #   )
+    #
+    # @example Cancel a forever order
+    #   order = DhanHQ::Models::ForeverOrder.find("5132208051112")
+    #   order.cancel  # => true
+    #
+    # @example List all forever orders
+    #   orders = DhanHQ::Models::ForeverOrder.all
+    #   orders.each { |order| puts order.order_status }
+    #
     class ForeverOrder < BaseModel
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
                  :transaction_type, :exchange_segment, :product_type, :order_flag,
@@ -13,17 +73,46 @@ module DhanHQ
                  :drv_strike_price
 
       class << self
-        # Provides a shared instance of the ForeverOrders resource
+        ##
+        # Provides a shared instance of the ForeverOrders resource.
         #
-        # @return [DhanHQ::Resources::ForeverOrders]
+        # @return [DhanHQ::Resources::ForeverOrders] The ForeverOrders resource client instance
         def resource
           @resource ||= DhanHQ::Resources::ForeverOrders.new
         end
 
         ##
-        # Fetch all forever orders
+        # Retrieves an array of all existing Forever Orders in the account.
+        #
+        # @return [Array<ForeverOrder>] Array of ForeverOrder objects. Returns empty array if no orders exist.
+        #   Each ForeverOrder object contains (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:order_id** [String] Order-specific identification generated by Dhan
+        #   - **:order_status** [String] Last updated status of the order.
+        #     Valid values: "TRANSIT", "PENDING", "REJECTED", "CANCELLED", "TRADED", "EXPIRED", "CONFIRM"
+        #   - **:transaction_type** [String] The trading side of transaction. Valid values: "BUY", "SELL"
+        #   - **:exchange_segment** [String] Exchange and segment. Valid values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "MCX_COMM"
+        #   - **:product_type** [String] Product type of trade. Valid values: "CNC", "INTRADAY", "MARGIN", "CO", "BO"
+        #   - **:order_type** [String] Order type. Valid values: "SINGLE", "OCO"
+        #   - **:trading_symbol** [String] Symbol of the instrument in which forever order is placed
+        #   - **:security_id** [String] Exchange standard ID for each scrip
+        #   - **:quantity** [Integer] Number of shares for the order
+        #   - **:price** [Float] Price at which order is placed
+        #   - **:trigger_price** [Float] Price at which order is to be triggered
+        #   - **:leg_name** [String] Order leg of Forever Order.
+        #     Valid values: "TARGET_LEG" (for Single and First leg of OCO), "STOP_LOSS_LEG" (for Second leg of OCO)
+        #   - **:create_time** [String] Time at which the Forever Order is created
+        #   - **:update_time** [String, nil] Time at which the Forever Order is updated
+        #   - **:exchange_time** [String, nil] Time at which order reached at exchange end
+        #   - **:drv_expiry_date** [String, nil] Contract Expiry Date for Derivative contract
+        #   - **:drv_option_type** [String, nil] Type of Option. Valid values: "CALL", "PUT"
+        #   - **:drv_strike_price** [Float] Strike Price in case of Option Contract
         #
-        # @return [Array<ForeverOrder>]
+        # @example List all forever orders
+        #   orders = DhanHQ::Models::ForeverOrder.all
+        #   orders.each do |order|
+        #     puts "#{order.order_id}: #{order.order_status} - #{order.trading_symbol}"
+        #   end
         def all
           response = resource.all
           return [] unless response.is_a?(Array)
@@ -32,10 +121,17 @@ module DhanHQ
         end
 
         ##
-        # Retrieve a specific forever order
+        # Retrieves a specific Forever Order by its order ID.
         #
-        # @param order_id [String]
-        # @return [ForeverOrder, nil]
+        # @param order_id [String] Order-specific identification generated by Dhan
+        # @return [ForeverOrder, nil] ForeverOrder object if found, nil otherwise
+        #
+        # @example Find a specific forever order
+        #   order = DhanHQ::Models::ForeverOrder.find("5132208051112")
+        #   if order
+        #     puts "Status: #{order.order_status}"
+        #     puts "Symbol: #{order.trading_symbol}"
+        #   end
         def find(order_id)
           response = resource.find(order_id)
           return nil unless response.is_a?(Hash) && response.any?
@@ -44,12 +140,86 @@ module DhanHQ
         end
 
         ##
-        # Create a new forever order
+        # Creates a new Forever Order (Good Till Triggered order).
+        #
+        # Forever Orders can be configured as SINGLE (one order) or OCO (One-Cancels-Other with two linked orders).
+        # The order remains active until triggered, modified, or cancelled.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float}] Forever order creation parameters
+        #   @option params [String] :dhan_client_id (required) User-specific identification generated by Dhan.
+        #     Must be explicitly provided in the params hash
+        #   @option params [String] :correlation_id (optional) User/partner generated ID for tracking purposes
+        #   @option params [String] :order_flag (required) Order flag type.
+        #     Valid values: "OCO" for OCO order, "SINGLE" for Forever Order
+        #   @option params [String] :transaction_type (required) The trading side of transaction.
+        #     Valid values: "BUY", "SELL"
+        #   @option params [String] :exchange_segment (required) Exchange and segment identifier.
+        #     Valid values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "BSE_FNO"
+        #   @option params [String] :product_type (required) Product type.
+        #     Valid values: "CNC", "MTF"
+        #   @option params [String] :order_type (required) Order type.
+        #     Valid values: "LIMIT", "MARKET"
+        #   @option params [String] :validity (required) Validity of order for execution.
+        #     Valid values: "DAY", "IOC"
+        #   @option params [String] :security_id (required) Exchange standard ID for each scrip
+        #   @option params [Integer] :quantity (required) Number of shares for the order
+        #   @option params [Integer] :disclosed_quantity (optional) Number of shares visible to market.
+        #     Keep more than 30% of quantity
+        #   @option params [Float] :price (required) Price at which order is placed
+        #   @option params [Float] :trigger_price (required) Price at which order is to be triggered
+        #   @option params [Float] :price1 (conditionally required) Target price for OCO order.
+        #     Required when order_flag is "OCO"
+        #   @option params [Float] :trigger_price1 (conditionally required) Target trigger price for OCO order.
+        #     Required when order_flag is "OCO"
+        #   @option params [Integer] :quantity1 (conditionally required) Target quantity for OCO order.
+        #     Required when order_flag is "OCO"
+        #
+        # @return [ForeverOrder, nil] ForeverOrder object with order details if creation succeeds, nil otherwise.
+        #   Response structure includes:
+        #   - **:order_id** [String] Order-specific identification generated by Dhan
+        #   - **:order_status** [String] Order status. Valid values: "TRANSIT", "PENDING", "REJECTED",
+        #     "CANCELLED", "TRADED", "EXPIRED", "CONFIRM"
+        #
+        # @example Create a single forever order
+        #   order = DhanHQ::Models::ForeverOrder.create(
+        #     dhan_client_id: "1000000132",
+        #     order_flag: "SINGLE",
+        #     transaction_type: "BUY",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "CNC",
+        #     order_type: "LIMIT",
+        #     validity: "DAY",
+        #     security_id: "1333",
+        #     quantity: 5,
+        #     disclosed_quantity: 1,
+        #     price: 1428.0,
+        #     trigger_price: 1427.0
+        #   )
+        #
+        # @example Create an OCO forever order
+        #   order = DhanHQ::Models::ForeverOrder.create(
+        #     dhan_client_id: "1000000132",
+        #     order_flag: "OCO",
+        #     transaction_type: "BUY",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "CNC",
+        #     order_type: "LIMIT",
+        #     validity: "DAY",
+        #     security_id: "1333",
+        #     quantity: 5,
+        #     price: 1428.0,
+        #     trigger_price: 1427.0,
+        #     price1: 1420.0,
+        #     trigger_price1: 1419.0,
+        #     quantity1: 10
+        #   )
         #
-        # @param params [Hash]
-        # @return [ForeverOrder, nil]
+        # @note Order placement APIs require Static IP whitelisting
         def create(params)
-          response = resource.create(params)
+          # Normalize params and auto-inject dhan_client_id from configuration if not provided
+          normalized_params = snake_case(params)
+          normalized_params[:dhan_client_id] ||= DhanHQ.configuration.client_id if DhanHQ.configuration.client_id
+          response = resource.create(normalized_params)
           return nil unless response.is_a?(Hash) && response["orderId"]
 
           find(response["orderId"])
@@ -57,27 +227,96 @@ module DhanHQ
       end
 
       ##
-      # Modify an existing forever order
+      # Modifies an existing Forever Order.
       #
-      # @param new_params [Hash]
-      # @return [ForeverOrder, nil]
+      # The variables that can be modified are: price, quantity, order_type, disclosed_quantity,
+      # trigger_price, and validity. For OCO orders, you can specify which leg to modify using leg_name.
+      #
+      # @param new_params [Hash{Symbol => String, Integer, Float}] Modification parameters
+      #   @option new_params [String] :dhan_client_id (required) User-specific identification generated by Dhan.
+      #     Must be explicitly provided in the params hash
+      #   @option new_params [String] :order_id (required) Order-specific identification generated by Dhan.
+      #     Must be explicitly provided in the params hash
+      #   @option new_params [String] :order_flag (required) Order flag type.
+      #     Valid values: "OCO" for OCO order, "SINGLE" for Forever Order
+      #   @option new_params [String] :order_type (required) Order type.
+      #     Valid values: "LIMIT", "MARKET", "STOP_LOSS", "STOP_LOSS_MARKET"
+      #   @option new_params [String] :leg_name (required) Order leg of Forever Order where modification is to be done.
+      #     Valid values: "TARGET_LEG" (for Single and First leg of OCO), "STOP_LOSS_LEG" (for Second leg of OCO)
+      #   @option new_params [Integer] :quantity (required) Number of shares for the order
+      #   @option new_params [Float] :price (required) Price at which order is placed
+      #   @option new_params [Integer] :disclosed_quantity (optional) Number of shares visible to market.
+      #     Keep more than 30% of quantity
+      #   @option new_params [Float] :trigger_price (required) Price at which order is to be triggered
+      #   @option new_params [String] :validity (required) Validity of order for execution.
+      #     Valid values: "DAY", "IOC"
+      #
+      # @return [ForeverOrder, nil] Updated ForeverOrder object if modification succeeds, nil otherwise.
+      #   Response structure includes:
+      #   - **:order_id** [String] Order-specific identification generated by Dhan
+      #   - **:order_status** [String] Last updated status of the order. Valid values: "TRANSIT", "PENDING",
+      #     "REJECTED", "CANCELLED", "TRADED", "EXPIRED", "CONFIRM"
+      #
+      # @example Modify a single forever order
+      #   order = DhanHQ::Models::ForeverOrder.find("5132208051112")
+      #   order.modify(
+      #     dhan_client_id: "1000000132",
+      #     order_id: "5132208051112",
+      #     order_flag: "SINGLE",
+      #     order_type: "LIMIT",
+      #     leg_name: "TARGET_LEG",
+      #     quantity: 15,
+      #     price: 1421.0,
+      #     disclosed_quantity: 1,
+      #     trigger_price: 1420.0,
+      #     validity: "DAY"
+      #   )
+      #
+      # @example Modify the stop loss leg of an OCO order
+      #   order.modify(
+      #     dhan_client_id: "1000000132",
+      #     order_id: "5132208051112",
+      #     order_flag: "OCO",
+      #     order_type: "LIMIT",
+      #     leg_name: "STOP_LOSS_LEG",
+      #     quantity: 10,
+      #     price: 1400.0,
+      #     trigger_price: 1399.0,
+      #     validity: "DAY"
+      #   )
+      #
+      # @raise [RuntimeError] If order_id is not available
+      # @note Order modification APIs require Static IP whitelisting
       def modify(new_params)
-        raise "Order ID is required to modify a forever order" unless id
+        raise "Order ID is required to modify a forever order" unless order_id
 
-        response = self.class.resource.update(id, new_params)
-        return self.class.find(id) if self.class.send(:success_response?, response)
+        response = self.class.resource.update(order_id, new_params)
+        return self.class.find(order_id) if self.class.send(:success_response?, response)
 
         nil
       end
 
       ##
-      # Cancel the forever order
+      # Cancels a pending Forever Order using the Order ID.
+      #
+      # @return [Boolean] true if cancellation succeeds (order_status becomes "CANCELLED"), false otherwise.
+      #   Response structure includes:
+      #   - **:order_id** [String] Order-specific identification generated by Dhan
+      #   - **:order_status** [String] Order status after cancellation. Valid values: "TRANSIT", "PENDING",
+      #     "REJECTED", "CANCELLED", "TRADED", "EXPIRED", "CONFIRM"
+      #
+      # @example Cancel a forever order
+      #   order = DhanHQ::Models::ForeverOrder.find("5132208051112")
+      #   if order.cancel
+      #     puts "Order #{order.order_id} cancelled successfully"
+      #   end
       #
-      # @return [Boolean]
+      # @raise [RuntimeError] If order_id is not available
+      # @note Order cancellation APIs require Static IP whitelisting
       def cancel
-        raise "Order ID is required to cancel a forever order" unless id
+        raise "Order ID is required to cancel a forever order" unless order_id
 
-        response = self.class.resource.cancel(id)
+        response = self.class.resource.cancel(order_id)
         response["orderStatus"] == "CANCELLED"
       end
     end

data/lib/DhanHQ/models/funds.rb

@@ -2,7 +2,26 @@
 
 module DhanHQ
   module Models
-    # Model representing the funds/limits endpoint response.
+    ##
+    # Model for retrieving trading account fund information including balance, margin utilized, collateral, etc.
+    #
+    # This endpoint provides comprehensive information about your trading account including available balance,
+    # start of day limit, collateral amounts, utilized amounts, and withdrawable balance.
+    #
+    # @example Fetch complete fund details
+    #   funds = DhanHQ::Models::Funds.fetch
+    #   puts "Available Balance: #{funds.available_balance}"
+    #   puts "Start of Day Limit: #{funds.sod_limit}"
+    #   puts "Utilized Amount: #{funds.utilized_amount}"
+    #   puts "Withdrawable Balance: #{funds.withdrawable_balance}"
+    #
+    # @example Fetch only available balance
+    #   balance = DhanHQ::Models::Funds.balance
+    #   puts "Available to trade: #{balance}"
+    #
+    # @note The API response contains a typo in the field name (`availabelBalance`). The model automatically
+    #   maps this to the correctly spelled `available_balance` attribute for convenience.
+    #
     class Funds < BaseModel
       # Base path used by the funds resource.
       HTTP_PATH = "/v2/fundlimit"
@@ -10,37 +29,84 @@ module DhanHQ
       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`.
+      ##
+      # Normalizes the typo'd `availabelBalance` key from the API response to `available_balance`.
+      #
+      # The API currently returns `availabelBalance` (note the typo). This method ensures backwards
+      # compatibility while exposing a correctly spelled attribute accessor.
+      #
+      # @return [void]
       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.
+        # Provides a shared instance of the Funds resource.
         #
-        # @return [DhanHQ::Resources::Funds]
+        # @return [DhanHQ::Resources::Funds] The Funds resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Funds.new
         end
 
         ##
-        # Fetch fund details.
+        # Fetches all fund limit details for your trading account.
+        #
+        # Retrieves comprehensive information about account balance, margin utilized, collateral,
+        # receivable amounts, and withdrawable balance. No request parameters are required.
+        #
+        # @return [Funds] Funds object containing all account fund information.
+        #   Response structure (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:available_balance** [Float] Available amount to trade
+        #   - **:sod_limit** [Float] Start of the day balance in account
+        #   - **:collateral_amount** [Float] Amount received against collateral
+        #   - **:receiveable_amount** [Float] Amount available against selling deliveries
+        #   - **:utilized_amount** [Float] Amount utilised in the day
+        #   - **:blocked_payout_amount** [Float] Amount blocked against payout request
+        #   - **:withdrawable_balance** [Float] Amount available to withdraw in bank account
+        #
+        # @example Fetch complete fund details
+        #   funds = DhanHQ::Models::Funds.fetch
+        #   puts "Available Balance: ₹#{funds.available_balance}"
+        #   puts "SOD Limit: ₹#{funds.sod_limit}"
+        #   puts "Utilized: ₹#{funds.utilized_amount}"
+        #   puts "Withdrawable: ₹#{funds.withdrawable_balance}"
         #
-        # @return [Fund]
+        # @example Check if sufficient balance for trading
+        #   funds = DhanHQ::Models::Funds.fetch
+        #   if funds.available_balance >= 10000.0
+        #     puts "Sufficient balance for trading"
+        #   else
+        #     puts "Low balance: ₹#{funds.available_balance}"
+        #   end
+        #
+        # @note This is a GET request with no body parameters required
         def fetch
           response = resource.fetch
           new(response, skip_validation: true)
         end
 
         ##
-        # Fetch only the available balance.
+        # Convenience method to fetch only the available balance.
+        #
+        # This method calls {fetch} internally and returns just the `available_balance` attribute,
+        # which is the amount available to trade.
+        #
+        # @return [Float] Available balance in the trading account (amount available to trade).
+        #   Returns 0.0 if unavailable or on error.
+        #
+        # @example Quick balance check
+        #   balance = DhanHQ::Models::Funds.balance
+        #   puts "Available to trade: ₹#{balance}"
         #
-        # @return [Float] Available balance in the trading account.
+        # @example Use in conditional logic
+        #   if DhanHQ::Models::Funds.balance > 50000
+        #     # Proceed with large order
+        #   end
         def balance
           fetch.available_balance
         end