DhanHQ 2.1.8 → 2.1.10

data/lib/DhanHQ/models/order.rb

@@ -6,7 +6,45 @@ 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.
+    ##
+    # Model for managing equity and F&O orders.
+    #
+    # The Order Management API lets you place new orders, cancel or modify pending orders,
+    # and retrieve order status, trade status, order book, and trade book. This model provides
+    # an ActiveRecord-style interface for order management operations.
+    #
+    # @note **Static IP Whitelisting**: Order placement, modification, and cancellation APIs
+    #   require Static IP whitelisting. Ensure your IP is whitelisted before using these endpoints.
+    #
+    # @example Place a new market order
+    #   order = DhanHQ::Models::Order.place(
+    #     dhan_client_id: "1000000003",
+    #     transaction_type: "BUY",
+    #     exchange_segment: "NSE_EQ",
+    #     product_type: "INTRADAY",
+    #     order_type: "MARKET",
+    #     validity: "DAY",
+    #     security_id: "11536",
+    #     quantity: 5
+    #   )
+    #   puts "Order placed: #{order.order_id} - #{order.order_status}"
+    #
+    # @example Modify an existing order
+    #   order = DhanHQ::Models::Order.find("112111182045")
+    #   order.modify(price: 3345.8, quantity: 40)
+    #   puts "Order modified: #{order.order_status}"
+    #
+    # @example Cancel an order
+    #   order = DhanHQ::Models::Order.find("112111182045")
+    #   if order.cancel
+    #     puts "Order cancelled successfully"
+    #   end
+    #
+    # @example Fetch all orders for the day
+    #   orders = DhanHQ::Models::Order.all
+    #   pending_orders = orders.select { |o| o.order_status == "PENDING" }
+    #   puts "Pending orders: #{pending_orders.count}"
+    #
     class Order < BaseModel
       # Attributes eligible for modification requests.
       MODIFIABLE_FIELDS = %i[
@@ -35,17 +73,36 @@ module DhanHQ
 
       class << self
         ##
-        # Provides a **shared instance** of the `Orders` resource
+        # Provides a shared instance of the Orders resource.
         #
-        # @return [DhanHQ::Resources::Orders]
+        # @return [DhanHQ::Resources::Orders] The Orders resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Orders.new
         end
 
         ##
-        # Fetch all orders for the day.
+        # Retrieves all orders placed during the current trading day.
+        #
+        # Fetches an array of all orders requested in a day with their last updated status.
+        # Returns empty array if no orders are found or if the response is not in the expected format.
+        #
+        # @return [Array<Order>] Array of Order objects. Returns empty array if no orders exist.
+        #   Each Order object contains comprehensive order details including status, timestamps,
+        #   quantities, prices, and error information if applicable.
+        #
+        # @example Fetch all orders for the day
+        #   orders = DhanHQ::Models::Order.all
+        #   puts "Total orders: #{orders.count}"
+        #   orders.each do |order|
+        #     puts "#{order.order_id}: #{order.order_status} - #{order.transaction_type} #{order.quantity}"
+        #   end
+        #
+        # @example Filter orders by status
+        #   orders = DhanHQ::Models::Order.all
+        #   pending = orders.select { |o| o.order_status == "PENDING" }
+        #   traded = orders.select { |o| o.order_status == "TRADED" }
+        #   puts "Pending: #{pending.count}, Traded: #{traded.count}"
         #
-        # @return [Array<Order>]
         def all
           response = resource.all
           return [] unless response.is_a?(Array)
@@ -54,10 +111,61 @@ module DhanHQ
         end
 
         ##
-        # Fetch a specific order by ID.
+        # Retrieves the details and status of a specific order by order ID.
+        #
+        # Fetches comprehensive order information including all order parameters, status,
+        # timestamps, trade information, and error details if the order was rejected.
+        #
+        # @param order_id [String] Order-specific identification generated by Dhan
+        #
+        # @return [Order, nil] Order object with complete details if found, nil otherwise.
+        #   Response structure includes (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:order_id** [String] Order-specific identification generated by Dhan
+        #   - **:correlation_id** [String] User/partner generated ID for tracking
+        #   - **:order_status** [String] Last updated status of the order.
+        #     Valid values: "TRANSIT", "PENDING", "REJECTED", "CANCELLED", "PART_TRADED",
+        #     "TRADED", "EXPIRED"
+        #   - **:transaction_type** [String] The trading side of transaction. "BUY" or "SELL"
+        #   - **:exchange_segment** [String] Exchange segment of instrument
+        #   - **:product_type** [String] Product type. Valid values: "CNC", "INTRADAY",
+        #     "MARGIN", "MTF", "CO", "BO"
+        #   - **:order_type** [String] Order type. Valid values: "LIMIT", "MARKET",
+        #     "STOP_LOSS", "STOP_LOSS_MARKET"
+        #   - **:validity** [String] Validity of order. "DAY" or "IOC"
+        #   - **:trading_symbol** [String] Trading symbol of the instrument
+        #   - **:security_id** [String] Exchange standard ID for each scrip
+        #   - **:quantity** [Integer] Number of shares for the order
+        #   - **:disclosed_quantity** [Integer] Number of shares visible
+        #   - **:price** [Float] Price at which order is placed
+        #   - **:trigger_price** [Float] Price at which order is triggered (for SL-M, SL-L, CO & BO)
+        #   - **:after_market_order** [Boolean] Whether the order placed is an AMO
+        #   - **:bo_profit_value** [Float] Bracket Order Target Price change
+        #   - **:bo_stop_loss_value** [Float] Bracket Order Stop Loss Price change
+        #   - **:leg_name** [String] Leg identification in case of BO.
+        #     Valid values: "ENTRY_LEG", "TARGET_LEG", "STOP_LOSS_LEG"
+        #   - **:create_time** [String] Time at which the order is created
+        #   - **:update_time** [String] Time at which the last activity happened
+        #   - **:exchange_time** [String] Time at which order reached at exchange
+        #   - **:drv_expiry_date** [String, nil] For F&O, expiry date of contract
+        #   - **:drv_option_type** [String, nil] Type of Option. "CALL" or "PUT"
+        #   - **:drv_strike_price** [Float] For Options, Strike Price
+        #   - **:oms_error_code** [String, nil] Error code if the order is rejected or failed
+        #   - **:oms_error_description** [String, nil] Description of error if the order is rejected
+        #   - **:algo_id** [String] Exchange Algo ID for Dhan
+        #   - **:remaining_quantity** [Integer] Quantity pending at the exchange to be traded
+        #     (quantity - filled_qty)
+        #   - **:average_traded_price** [Float] Average price at which order is traded
+        #   - **:filled_qty** [Integer] Quantity of order traded on Exchange
+        #
+        # @example Fetch order details
+        #   order = DhanHQ::Models::Order.find("112111182198")
+        #   if order
+        #     puts "Status: #{order.order_status}"
+        #     puts "Quantity: #{order.quantity}, Filled: #{order.filled_qty}"
+        #     puts "Remaining: #{order.remaining_quantity}"
+        #   end
         #
-        # @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?)
@@ -67,10 +175,24 @@ module DhanHQ
         end
 
         ##
-        # Fetch a specific order by correlation ID.
+        # Retrieves the status of an order using a user-supplied correlation ID.
+        #
+        # Useful when you need to track orders using your own correlation ID instead of
+        # the Dhan-generated order ID. This is helpful if you missed the order ID due to
+        # unforeseen reasons but have your correlation ID stored.
+        #
+        # @param correlation_id [String] The user/partner generated ID for tracking
+        #
+        # @return [Order, nil] Order object with complete details if found, nil otherwise.
+        #   Response structure is the same as {find}.
+        #
+        # @example Fetch order by correlation ID
+        #   order = DhanHQ::Models::Order.find_by_correlation("123abc678")
+        #   if order
+        #     puts "Order ID: #{order.order_id}"
+        #     puts "Status: #{order.order_status}"
+        #   end
         #
-        # @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"
@@ -78,12 +200,94 @@ module DhanHQ
           new(response, skip_validation: true)
         end
 
-        # Place a new order
+        ##
+        # Places a new order.
+        #
+        # Validates order parameters and places a new order via the API. After successful
+        # placement, fetches and returns the complete order details including the generated
+        # order ID and current status.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float, Boolean}] Order placement 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.
+        #     Max length: 25 characters
+        #   @option params [String] :transaction_type (required) The trading side of transaction.
+        #     Valid values: "BUY", "SELL"
+        #   @option params [String] :exchange_segment (required) Exchange and segment of instrument.
+        #     Valid values: See {DhanHQ::Constants::EXCHANGE_SEGMENTS}
+        #   @option params [String] :product_type (required) Product type.
+        #     Valid values: "CNC", "INTRADAY", "MARGIN", "MTF", "CO", "BO"
+        #   @option params [String] :order_type (required) Order type.
+        #     Valid values: "LIMIT", "MARKET", "STOP_LOSS", "STOP_LOSS_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. Must be greater than 0
+        #   @option params [Integer] :disclosed_quantity (optional) Number of shares visible to market.
+        #     Keep more than 30% of quantity if providing. Must be >= 0 if provided
+        #   @option params [Float] :price (conditionally required) Price at which order is placed.
+        #     Required for LIMIT orders. Must be > 0 if provided
+        #   @option params [Float] :trigger_price (conditionally required) Price at which the order is triggered.
+        #     Required for STOP_LOSS and STOP_LOSS_MARKET order types. Must be > 0 if provided
+        #   @option params [Boolean] :after_market_order (optional) Flag for orders placed after market hours
+        #   @option params [String] :amo_time (conditionally required) Timing to place the after market order.
+        #     Required when after_market_order is true.
+        #     Valid values: "PRE_OPEN", "OPEN", "OPEN_30", "OPEN_60"
+        #   @option params [Float] :bo_profit_value (conditionally required) Bracket Order Target Price change.
+        #     Required for BO product type. Must be > 0 if provided
+        #   @option params [Float] :bo_stop_loss_value (conditionally required) Bracket Order Stop Loss Price change.
+        #     Required for BO product type. Must be > 0 if provided
         #
-        # @param params [Hash] Order parameters
-        # @return [Order]
+        # @return [Order, nil] Order object with complete details if placement succeeds, nil otherwise.
+        #   The order object includes the generated :order_id and current :order_status.
+        #
+        # @example Place a market order
+        #   order = DhanHQ::Models::Order.place(
+        #     dhan_client_id: "1000000003",
+        #     transaction_type: "BUY",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "INTRADAY",
+        #     order_type: "MARKET",
+        #     validity: "DAY",
+        #     security_id: "11536",
+        #     quantity: 5
+        #   )
+        #   puts "Order ID: #{order.order_id}"
+        #   puts "Status: #{order.order_status}"
+        #
+        # @example Place a limit order
+        #   order = DhanHQ::Models::Order.place(
+        #     dhan_client_id: "1000000003",
+        #     transaction_type: "BUY",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "CNC",
+        #     order_type: "LIMIT",
+        #     validity: "DAY",
+        #     security_id: "11536",
+        #     quantity: 10,
+        #     price: 1500.0
+        #   )
+        #
+        # @example Place a stop-loss order
+        #   order = DhanHQ::Models::Order.place(
+        #     dhan_client_id: "1000000003",
+        #     transaction_type: "SELL",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "INTRADAY",
+        #     order_type: "STOP_LOSS",
+        #     validity: "DAY",
+        #     security_id: "11536",
+        #     quantity: 5,
+        #     price: 1480.0,
+        #     trigger_price: 1490.0
+        #   )
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter
         def place(params)
           normalized_params = snake_case(params)
+          # Auto-inject dhan_client_id from configuration if not provided
+          normalized_params[:dhan_client_id] ||= DhanHQ.configuration.client_id if DhanHQ.configuration.client_id
           validate_params!(normalized_params, DhanHQ::Contracts::PlaceOrderContract)
 
           response = resource.create(camelize_keys(normalized_params))
@@ -94,11 +298,29 @@ module DhanHQ
         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)
+        # ActiveRecord-style create method.
+        #
+        # Creates a new Order instance, validates it, and saves it. This provides an
+        # ActiveRecord-like interface: `Order.create(params)` or `Order.new(params).save`.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float, Boolean}] Order creation parameters.
+        #   See {place} for parameter details.
+        #
+        # @return [Order] Order instance. Note that validation failures may result in an
+        #   invalid order that couldn't be saved.
+        #
+        # @example Create order using AR-style method
+        #   order = DhanHQ::Models::Order.create(
+        #     dhan_client_id: "1000000003",
+        #     transaction_type: "BUY",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "INTRADAY",
+        #     order_type: "MARKET",
+        #     validity: "DAY",
+        #     security_id: "11536",
+        #     quantity: 5
+        #   )
         #
-        # 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?
@@ -108,10 +330,39 @@ module DhanHQ
         end
       end
 
-      # Modify the order while preserving existing attributes
+      ##
+      # Modifies a pending order in the orderbook.
+      #
+      # Allows modification of price, quantity, order type, and validity for pending orders.
+      # The method preserves existing attributes and only updates the fields specified in
+      # `new_params`. Only modifiable fields are included in the update request.
+      #
+      # @param new_params [Hash{Symbol => String, Integer, Float}] Fields to modify.
+      #   Only modifiable fields are accepted:
+      #   @option new_params [String] :order_type (optional) New order type.
+      #     Valid values: "LIMIT", "MARKET", "STOP_LOSS", "STOP_LOSS_MARKET"
+      #   @option new_params [Integer] :quantity (optional) New quantity to modify
+      #   @option new_params [Float] :price (optional) New price to modify
+      #   @option new_params [Float] :trigger_price (optional) New trigger price for SL-M and SL-L orders
+      #   @option new_params [Integer] :disclosed_quantity (optional) New disclosed quantity
+      #   @option new_params [String] :validity (optional) New validity. "DAY" or "IOC"
+      #   @option new_params [String] :leg_name (optional) Leg identification for BO & CO orders.
+      #     Valid values: "ENTRY_LEG", "TARGET_LEG", "STOP_LOSS_LEG"
+      #
+      # @return [Order, ErrorObject] Updated Order object on success, ErrorObject on failure.
+      #   The order's attributes are updated with the latest values from the API response.
       #
-      # @param new_params [Hash]
-      # @return [Order, nil]
+      # @example Modify order price and quantity
+      #   order = DhanHQ::Models::Order.find("112111182045")
+      #   order.modify(price: 3345.8, quantity: 40)
+      #   puts "Modified: #{order.order_status}"
+      #
+      # @example Modify order validity
+      #   order = DhanHQ::Models::Order.find("112111182045")
+      #   order.modify(validity: "IOC")
+      #
+      # @raise [RuntimeError] If order ID is missing
+      # @raise [DhanHQ::ValidationError] If validation fails for any parameter
       def modify(new_params)
         raise "Order ID is required to modify an order" unless id
 
@@ -138,9 +389,23 @@ module DhanHQ
         self
       end
 
-      # Cancel the order
+      ##
+      # Cancels a pending order in the orderbook.
       #
-      # @return [Boolean]
+      # Cancels an existing order using its order ID. Returns true if the cancellation
+      # was successful (order status becomes "CANCELLED").
+      #
+      # @return [Boolean] true if cancellation succeeds, false otherwise
+      #
+      # @example Cancel a pending order
+      #   order = DhanHQ::Models::Order.find("112111182045")
+      #   if order.cancel
+      #     puts "Order cancelled successfully"
+      #   else
+      #     puts "Failed to cancel order"
+      #   end
+      #
+      # @raise [RuntimeError] If order ID is missing
       def cancel
         raise "Order ID is required to cancel an order" unless id
 
@@ -148,9 +413,21 @@ module DhanHQ
         response["orderStatus"] == "CANCELLED"
       end
 
-      # Fetch the latest details of the order
+      ##
+      # Fetches the latest details and status of the order.
       #
-      # @return [Order, nil]
+      # Refreshes the order object with the most current information from the API,
+      # including updated status, trade information, and any other changes.
+      #
+      # @return [Order, nil] Updated Order object with latest details, nil if order not found
+      #
+      # @example Refresh order status
+      #   order = DhanHQ::Models::Order.find("112111182198")
+      #   order.refresh
+      #   puts "Updated status: #{order.order_status}"
+      #   puts "Filled: #{order.filled_qty}/#{order.quantity}"
+      #
+      # @raise [RuntimeError] If order ID is missing
       def refresh
         raise "Order ID is required to refresh an order" unless id
 
@@ -158,20 +435,56 @@ module DhanHQ
       end
 
       ##
-      # This is how we figure out if it's an existing record or not:
+      # Checks if this is a new (unsaved) order record.
+      #
+      # Determines whether the order has been saved to the API or is a new instance
+      # that hasn't been placed yet. Used internally to decide between create and update operations.
+      #
+      # @return [Boolean] true if order_id is nil or empty (new record), false otherwise
+      #
+      # @api private
       def new_record?
         order_id.nil? || order_id.to_s.empty?
       end
 
       ##
-      # The ID used for resource calls
+      # Returns the order ID used for resource calls.
+      #
+      # Provides a consistent identifier method for API operations. This is an alias
+      # for `order_id` that follows ActiveRecord conventions.
+      #
+      # @return [String, nil] Order ID if present, nil otherwise
+      #
+      # @api private
       def id
         order_id
       end
 
       ##
-      # Save: If new_record?, do resource.create
-      # else resource.update
+      # Saves the order (places new or modifies existing).
+      #
+      # For new records (no order_id), places a new order via the API.
+      # For existing records (has order_id), modifies the order via the API.
+      # The order's attributes are updated with the API response after successful save.
+      #
+      # @return [Boolean] true if save succeeds, false otherwise
+      #
+      # @example Save a new order
+      #   order = DhanHQ::Models::Order.new(
+      #     dhan_client_id: "1000000003",
+      #     transaction_type: "BUY",
+      #     exchange_segment: "NSE_EQ",
+      #     product_type: "INTRADAY",
+      #     order_type: "MARKET",
+      #     validity: "DAY",
+      #     security_id: "11536",
+      #     quantity: 5
+      #   )
+      #   if order.save
+      #     puts "Order placed: #{order.order_id}"
+      #   end
+      #
+      # @note Validation is performed before save. Invalid orders will not be saved.
       def save
         return false unless valid?
 
@@ -200,7 +513,21 @@ module DhanHQ
       end
 
       ##
-      # Cancel => calls resource.delete
+      # Cancels (destroys) the order.
+      #
+      # Cancels an existing order by calling the delete endpoint. This is an alias
+      # for the cancel operation following ActiveRecord conventions.
+      #
+      # @return [Boolean] true if cancellation succeeds (order status becomes "CANCELLED"),
+      #   false otherwise
+      #
+      # @example Destroy an order
+      #   order = DhanHQ::Models::Order.find("112111182045")
+      #   if order.destroy
+      #     puts "Order cancelled"
+      #   end
+      #
+      # @note This method does nothing for new (unsaved) orders.
       def destroy
         return false if new_record?
 
@@ -215,8 +542,38 @@ module DhanHQ
       alias delete destroy
 
       ##
-      # Slicing (optional)
-      # If you want an AR approach:
+      # Slices an order into multiple legs to place orders over freeze limit quantity.
+      #
+      # This API helps you slice your order request into multiple orders to allow you
+      # to place over freeze limit quantity for F&O instruments. Returns an array of
+      # orders created from the slice operation.
+      #
+      # @param params [Hash{Symbol => String, Integer, Float, Boolean}] Order parameters for slicing.
+      #   Same parameters as {place}, but quantity can exceed freeze limits as it will be
+      #   automatically split into multiple orders.
+      #
+      # @return [Array<Hash>] Array of order objects created from the slice operation.
+      #   Each hash contains:
+      #   - **:order_id** [String] Order-specific identification generated by Dhan
+      #   - **:order_status** [String] Order status. Valid values: "TRANSIT", "PENDING",
+      #     "REJECTED", "CANCELLED", "TRADED", "EXPIRED", "CONFIRM"
+      #
+      # @example Slice a large order
+      #   order = DhanHQ::Models::Order.find("112111182045")
+      #   sliced_orders = order.slice_order(
+      #     dhan_client_id: "1000000003",
+      #     transaction_type: "BUY",
+      #     exchange_segment: "NSE_FNO",
+      #     product_type: "INTRADAY",
+      #     order_type: "MARKET",
+      #     validity: "DAY",
+      #     security_id: "49081",
+      #     quantity: 50000  # Will be split into multiple orders
+      #   )
+      #   puts "Created #{sliced_orders.count} orders"
+      #
+      # @raise [RuntimeError] If order ID is missing
+      # @raise [DhanHQ::ValidationError] If validation fails for any parameter
       def slice_order(params)
         raise "Order ID is required to slice an order" unless id
 
@@ -229,8 +586,16 @@ module DhanHQ
       end
 
       ##
-      # Because we have two separate contracts: place vs. modify
-      # We can do something like:
+      # Returns the appropriate validation contract based on order state.
+      #
+      # For new records, returns PlaceOrderContract. For existing records, returns
+      # ModifyOrderContract. This allows the same validation logic to be used for
+      # both creating and modifying orders.
+      #
+      # @return [DhanHQ::Contracts::PlaceOrderContract, DhanHQ::Contracts::ModifyOrderContract]
+      #   The appropriate validation contract based on whether this is a new or existing order
+      #
+      # @api private
       def validation_contract
         new_record? ? DhanHQ::Contracts::PlaceOrderContract.new : DhanHQ::Contracts::ModifyOrderContract.new
       end