DhanHQ 2.1.7 → 2.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ffcb72b2997f7841ef6c872ad71748c36f4305f9e746a5d4d8f2a3b9429c8da
-  data.tar.gz: 5a72519746d9ca58f6cb295855f9065ccc3b9059c2684347b58c3e998ad8668b
+  metadata.gz: 300207afdb6b293a9b73b5cf6d2bb11da0eb8251bed6ab489c115287ab201051
+  data.tar.gz: 49fde0cde20215c959d167860529ccaa2e984b1aa46653f8024a463a8ff8db53
 SHA512:
-  metadata.gz: 397d51627f7049470332e23926ca7d00d78aad94d88eb0939d25164dc74330d68014a5ad6593453dfedb2da51c4f2a810ecc7e971d5f1735b3b21e96d3d068df
-  data.tar.gz: 2092c00ab1903f18d7718bd27125236251d2129cd536a071b506c3a53d2826a66eb5c9ba737ab89eff52b125e864138b507e577616ffc9e0a034da0a4eb8e37a
+  metadata.gz: eb75dbe33b1c937cb825dde8f8a2e86748f1fce2f230a52190ca5862a900f40b64d7f17319cf34c6847253d5c98ab42396e6ee5d46b9ae66c26c34c473d7fb69
+  data.tar.gz: d491b32c1ec671414d2d1c7bdef765cde05631bca5be3c41ff1df66d7060901b6e58b5612092891e25b3d06b7b920525ef69097a91b3104cdd2364b8c97c3a6f

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 ## [Unreleased]
 
+## [2.1.10] - 2025-11-11
+
+### Fixed
+- Expired Options Data routing: send `client-id` header for `/v2/charts/rollingoption` by adding `/v2/charts/` to data API prefixes.
+- Correct `HTTP_PATH` for `ExpiredOptionsData` resource to `/v2/charts`.
+- Prevent false validation failures by allowing up to 31-day ranges (to_date non-inclusive).
+
+### Changed
+- Align `ExpiredOptionsData` contract with broker docs:
+  - `interval` accepted as String (e.g., "1", "5", "15", "25", "60").
+  - `security_id` validated as Integer.
+- Input normalization for `ExpiredOptionsData.fetch`:
+  - Coerce convertible types (`interval`, `security_id`, `expiry_code`).
+  - Uppercase enums and `strike`, normalize `required_data` to downcased unique list.
+- Improved examples and YARD docs to reflect the above.
+
+## [2.1.9] - 2025-01-31
+
+### Added
+- **Comprehensive YARD documentation**: Added complete YARD documentation across all model classes with detailed parameter specifications, return types, and examples:
+  - `DhanHQ::Models::Edis` - EDIS form, bulk form, TPIN, and inquiry methods documented
+  - `DhanHQ::Models::ExpiredOptionsData` - Expired options data fetching with strike analysis helpers
+  - `DhanHQ::Models::ForeverOrder` - Forever Order (GTT) creation, modification, and cancellation
+  - `DhanHQ::Models::Funds` - Account fund information retrieval
+  - `DhanHQ::Models::HistoricalData` - Daily and intraday historical candle data fetching
+  - `DhanHQ::Models::Holding` - Portfolio holdings retrieval
+  - `DhanHQ::Models::Margin` - Margin calculation for orders
+  - `DhanHQ::Models::MarketFeed` - LTP, OHLC, and quote data fetching
+  - `DhanHQ::Models::OptionChain` - Option chain data and expiry list fetching
+  - `DhanHQ::Models::Order` - Order placement, modification, cancellation, and slicing
+  - `DhanHQ::Models::Position` - Position management and conversion
+  - `DhanHQ::Models::SuperOrder` - Multi-leg super order management
+  - `DhanHQ::Models::Trade` - Trade book, order trades, and historical trades
+  - `DhanHQ::Models::Profile` - User profile and account information
+  - `DhanHQ::Models::KillSwitch` - Kill switch activation and deactivation
+- All documentation includes:
+  - Complete parameter documentation with types, descriptions, and valid values
+  - Comprehensive return type specifications with response structure details
+  - Multiple practical examples for each method
+  - Response field normalization (snake_case) documentation
+  - Error handling documentation with `@raise` tags
+  - Special notes and prerequisites where applicable
+
+### Changed
+- **Documentation standards**: All model documentation now follows YARD best practices with:
+  - Properly indented `@option` tags for better readability
+  - Consistent use of YARD hash syntax for parameter and return types
+  - Detailed response structure documentation with field types and descriptions
+  - Clarified that `dhan_client_id` must be explicitly provided (not auto-injected) where applicable
+
+## [2.1.8] - 2025-10-30
+
+### Fixed
+- Correctly map `underlying_seg` for option chain APIs:
+  - Index instruments use `IDX_I`.
+  - Stocks map to `NSE_FNO` or `BSE_FNO` based on the instrument's exchange.
+- Implemented via `underlying_segment_for_options` in `DhanHQ::Models::InstrumentHelpers` and applied to `expiry_list` and `option_chain`.
+
 ## [2.1.7] - 2025-01-28
 
 ### Added

data/examples/live_order_updates.rb

@@ -101,7 +101,7 @@ summary_timer = Thread.new do
       end
     end
 
-    puts "\n" + ("=" * 50)
+    puts "\n#{"=" * 50}"
   end
 end
 

data/examples/market_depth_example.rb

@@ -74,14 +74,14 @@ depth_client = DhanHQ::WS::MarketDepth.connect(symbols: symbols) do |depth_data|
   puts "  Ask Levels: #{depth_data[:asks].size}"
 
   # Show top 3 bid/ask levels if available
-  if depth_data[:bids] && depth_data[:bids].size > 0
+  if depth_data[:bids]&.size&.positive?
     puts "  Top Bids:"
     depth_data[:bids].first(3).each_with_index do |bid, i|
       puts "    #{i + 1}. Price: #{bid[:price]}, Qty: #{bid[:quantity]}"
     end
   end
 
-  if depth_data[:asks] && depth_data[:asks].size > 0
+  if depth_data[:asks]&.size&.positive?
     puts "  Top Asks:"
     depth_data[:asks].first(3).each_with_index do |ask, i|
       puts "    #{i + 1}. Price: #{ask[:price]}, Qty: #{ask[:quantity]}"

data/examples/trading_fields_example.rb

@@ -109,7 +109,7 @@ def calculate_margin_requirements(instrument, name, quantity, price)
   puts "   Sell CO Margin Required: ₹#{sell_margin}"
 
   # Calculate MTF leverage
-  if instrument.mtf_leverage > 0
+  if instrument.mtf_leverage.positive?
     mtf_value = total_value * instrument.mtf_leverage
     puts "   MTF Leverage: #{instrument.mtf_leverage}x"
     puts "   MTF Value: ₹#{mtf_value}"

data/lib/DhanHQ/client.rb

@@ -38,7 +38,8 @@ module DhanHQ
     # @return [DhanHQ::Client] A new client instance.
     def initialize(api_type:)
       DhanHQ.configure_with_env if ENV.fetch("CLIENT_ID", nil)
-      @rate_limiter = RateLimiter.new(api_type)
+      # Use shared rate limiter instance per API type to ensure proper coordination
+      @rate_limiter = RateLimiter.for(api_type)
 
       raise "RateLimiter initialization failed" unless @rate_limiter
 

data/lib/DhanHQ/contracts/expired_options_data_contract.rb

@@ -10,8 +10,8 @@ module DhanHQ
     class ExpiredOptionsDataContract < BaseContract
       params do
         required(:exchange_segment).filled(:string)
-        required(:interval).filled(:integer)
-        required(:security_id).filled(:string)
+        required(:interval).filled(:string)
+        required(:security_id).filled(:integer)
         required(:instrument).filled(:string)
         required(:expiry_flag).filled(:string)
         required(:expiry_code).filled(:integer)
@@ -28,7 +28,7 @@ module DhanHQ
       end
 
       rule(:interval) do
-        valid_intervals = [1, 5, 15, 25, 60]
+        valid_intervals = %w[1 5 15 25 60]
         key.failure("must be one of: #{valid_intervals.join(", ")}") unless valid_intervals.include?(value)
       end
 
@@ -69,10 +69,10 @@ module DhanHQ
             from_date = Date.parse(values[:from_date])
             to_date = Date.parse(values[:to_date])
 
-            key.failure("from_date must be before to_date") if from_date >= to_date
+            key.failure("from_date must be on or before to_date") if from_date > to_date
 
-            # Check if date range is not too large (max 30 days)
-            key.failure("date range cannot exceed 30 days") if (to_date - from_date).to_i > 30
+            # Check if date range is not too large (max 31 days; to_date is non-inclusive)
+            key.failure("date range cannot exceed 31 days") if (to_date - from_date).to_i > 31
 
             # Check if from_date is not too far in the past (max 5 years)
             five_years_ago = Date.today - (5 * 365)

data/lib/DhanHQ/core/base_model.rb

@@ -222,9 +222,17 @@ module DhanHQ
 
     # Format request parameters before sending to API
     #
+    # Auto-injects dhan_client_id from configuration if not present in attributes
+    # and the model requires it (has dhan_client_id as an attribute).
+    #
     # @return [Hash] The camelCased attributes
     def to_request_params
-      optionchain_api? ? titleize_keys(@attributes) : camelize_keys(@attributes)
+      attrs = @attributes.dup
+      # Auto-inject dhan_client_id from configuration if not provided and model supports it
+      if self.class.defined_attributes&.include?("dhan_client_id") && !attrs[:dhan_client_id] && DhanHQ.configuration.client_id
+        attrs[:dhan_client_id] = DhanHQ.configuration.client_id
+      end
+      optionchain_api? ? titleize_keys(attrs) : camelize_keys(attrs)
     end
 
     # Identifier inferred from the loaded attributes.

data/lib/DhanHQ/models/edis.rb

@@ -2,54 +2,190 @@
 
 module DhanHQ
   module Models
-    # Model wrapper for electronic DIS flows.
+    ##
+    # Model wrapper for electronic DIS (Delivery Instruction Slip) flows.
+    #
+    # To sell holding stocks, one needs to complete the CDSL eDIS flow:
+    # 1. Generate T-PIN using {tpin}
+    # 2. Retrieve escaped HTML form using {form} and enter T-PIN to mark stock for EDIS approval
+    # 3. Check status using {inquire} to verify if stock is approved and marked for sell action
+    #
+    # You can get ISIN (International Securities Identification Number) of portfolio stocks
+    # from the holdings API response.
+    #
+    # @example Generate T-PIN
+    #   response = DhanHQ::Models::Edis.tpin
+    #   # Returns 202 Accepted status
+    #
+    # @example Generate eDIS form for a single stock
+    #   response = DhanHQ::Models::Edis.form(
+    #     isin: "INE733E01010",
+    #     qty: 1,
+    #     exchange: "NSE",
+    #     segment: "EQ",
+    #     bulk: false
+    #   )
+    #   # => {
+    #   #   dhan_client_id: "1000000401",
+    #   #   edis_form_html: "<!DOCTYPE html>..."
+    #   # }
+    #
+    # @example Check EDIS status for an ISIN
+    #   status = DhanHQ::Models::Edis.inquire("INE00IN01015")
+    #   # => {
+    #   #   client_id: "1000000401",
+    #   #   isin: "INE00IN01015",
+    #   #   total_qty: "10",
+    #   #   aprvd_qty: "4",
+    #   #   status: "SUCCESS",
+    #   #   remarks: "eDIS transaction done successfully"
+    #   # }
+    #
     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]
+        # @return [DhanHQ::Resources::Edis] The EDIS resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Edis.new
         end
 
-        # Submits an EDIS form request.
+        ##
+        # Retrieves escaped HTML form of CDSL and enters T-PIN to mark the stock for EDIS approval.
         #
-        # @param params [Hash]
-        # @return [Hash]
+        # User has to render this form at their end to unescape. The form contains hidden fields
+        # that will automatically submit to CDSL's eDIS verification endpoint.
+        #
+        # @param params [Hash{Symbol => String, Integer, Boolean}] The EDIS form request parameters
+        #   @option params [String] :isin (required) International Securities Identification Number
+        #     (12-digit alphanumeric code). You can get ISIN from the holdings API response.
+        #   @option params [Integer] :qty (required) Number of shares to mark for EDIS transaction
+        #   @option params [String] :exchange (required) Exchange identifier. Must be either "NSE" or "BSE"
+        #   @option params [String] :segment (required) Segment identifier. Must be "EQ"
+        #   @option params [Boolean] :bulk (optional, default: false) Set to true to mark EDIS for
+        #     all stocks in portfolio. When true, other parameters may be ignored.
+        #
+        # @return [Hash{Symbol => String}] The EDIS form response containing escaped HTML form.
+        #   Response keys are normalized to snake_case:
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:edis_form_html** [String] Escaped HTML form that needs to be rendered and unescaped
+        #
+        # @example Generate form for a single stock
+        #   response = DhanHQ::Models::Edis.form(
+        #     isin: "INE733E01010",
+        #     qty: 1,
+        #     exchange: "NSE",
+        #     segment: "EQ",
+        #     bulk: false
+        #   )
+        #   html_form = response[:edis_form_html]
+        #   # Render and unescape the HTML form to complete EDIS approval
+        #
+        # @example Generate form for bulk EDIS
+        #   response = DhanHQ::Models::Edis.form(
+        #     isin: "",
+        #     qty: 0,
+        #     exchange: "NSE",
+        #     segment: "EQ",
+        #     bulk: true
+        #   )
         def form(params)
           resource.form(params)
         end
 
-        # Submits a bulk EDIS form request.
+        ##
+        # Submits a bulk EDIS form request for multiple stocks.
         #
-        # @param params [Hash]
-        # @return [Hash]
+        # This is an alternative to using {form} with `bulk: true`. The exact parameter
+        # structure may differ from the single form request.
+        #
+        # @param params [Hash{Symbol => String, Integer, Boolean}] The bulk EDIS form request parameters
+        #   @option params [String] :isin (optional) International Securities Identification Number.
+        #     May be ignored for bulk requests
+        #   @option params [Integer] :qty (optional) Number of shares. May be ignored for bulk requests
+        #   @option params [String] :exchange (required) Exchange identifier ("NSE" or "BSE")
+        #   @option params [String] :segment (required) Segment identifier ("EQ")
+        #   @option params [Boolean] :bulk (optional, default: true) Set to true for bulk operations
+        #
+        # @return [Hash{Symbol => String}] The bulk EDIS form response containing escaped HTML form.
+        #   Response keys are normalized to snake_case:
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:edis_form_html** [String] Escaped HTML form that needs to be rendered and unescaped
+        #
+        # @example Bulk EDIS form request
+        #   response = DhanHQ::Models::Edis.bulk_form(
+        #     exchange: "NSE",
+        #     segment: "EQ",
+        #     bulk: true
+        #   )
         def bulk_form(params)
           resource.bulk_form(params)
         end
 
-        # Requests a TPIN for the configured client.
+        ##
+        # Generates a T-PIN (Transaction PIN) for the configured client.
+        #
+        # T-PIN is sent to the user's registered mobile number. This T-PIN is required
+        # when submitting the EDIS form to mark stocks for sell action.
         #
-        # @return [Hash]
+        # @return [Hash{Symbol => String}] The T-PIN generation response. The T-PIN itself is sent
+        #   to the registered mobile number and not returned in the response. Response typically
+        #   contains a status indicating successful generation (e.g., "202 Accepted").
+        #
+        # @example Generate T-PIN
+        #   response = DhanHQ::Models::Edis.tpin
+        #   # T-PIN will be sent to registered mobile number
+        #   # Check your mobile for the T-PIN before submitting the EDIS form
+        #
+        # @note This is a GET request with no body parameters required
         def tpin
           resource.tpin
         end
 
-        # Inquires EDIS status for a specific ISIN.
+        ##
+        # Inquires the EDIS status for a specific ISIN to check if stock is approved and marked for sell action.
+        #
+        # You can check whether a stock has been approved through the EDIS process and is ready
+        # for sell action. Alternatively, you can pass "ALL" instead of an ISIN to get EDIS status
+        # of all holdings in your portfolio.
+        #
+        # @param isin [String] International Securities Identification Number (12-digit alphanumeric code).
+        #   You can get ISIN from the holdings API response. Alternatively, pass "ALL" to get status
+        #   for all holdings in your portfolio.
+        #
+        # @return [Hash{Symbol => String}] The EDIS inquiry response containing status information.
+        #   Response keys are normalized to snake_case:
+        #   - **:client_id** [String] User-specific identification
+        #   - **:isin** [String] International Securities Identification Number that was queried
+        #   - **:total_qty** [String] Total number of shares for the given stock
+        #   - **:aprvd_qty** [String] Number of approved stocks that are marked for EDIS
+        #   - **:status** [String] Status of the EDIS order (e.g., "SUCCESS", "PENDING", "FAILED")
+        #   - **:remarks** [String] Remarks about the order status (e.g., "eDIS transaction done successfully")
+        #
+        # @example Check status for a specific ISIN
+        #   status = DhanHQ::Models::Edis.inquire("INE00IN01015")
+        #   puts status[:status]       # => "SUCCESS"
+        #   puts status[:aprvd_qty]    # => "4"
+        #   puts status[:total_qty]     # => "10"
+        #
+        # @example Check status for all holdings
+        #   all_status = DhanHQ::Models::Edis.inquire("ALL")
+        #   # Returns status for all holdings in portfolio
         #
-        # @param isin [String]
-        # @return [Hash]
+        # @note This is a GET request with no body parameters. The ISIN is passed in the URL path.
         def inquire(isin)
           resource.inquire(isin)
         end
       end
 
+      ##
       # EDIS payloads are validated upstream so no contract is applied.
       #
-      # @return [nil]
+      # @return [nil] No validation contract is needed for EDIS operations
       def validation_contract
         nil
       end