DhanHQ 2.3.0 → 2.5.0

data/lib/DhanHQ/models/pnl_exit.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Model for managing P&L-based automatic position exit.
+    #
+    # The P&L Based Exit API allows users to configure automatic exit rules based on
+    # cumulative profit or loss thresholds. When the defined limits are breached, all
+    # applicable positions are exited automatically.
+    #
+    # @note The configured P&L based exit remains active for the current day and is
+    #   reset at the end of the trading session.
+    #
+    # @example Configure P&L-based exit
+    #   response = DhanHQ::Models::PnlExit.configure(
+    #     profit_value: 1500.0,
+    #     loss_value: 500.0,
+    #     product_type: ["INTRADAY", "DELIVERY"],
+    #     enable_kill_switch: true
+    #   )
+    #   puts response[:pnl_exit_status] # => "ACTIVE"
+    #
+    # @example Check current P&L exit configuration
+    #   config = DhanHQ::Models::PnlExit.status
+    #   puts "Status: #{config.pnl_exit_status}"
+    #   puts "Profit threshold: ₹#{config.profit}"
+    #   puts "Loss threshold: ₹#{config.loss}"
+    #
+    # @example Stop P&L-based exit
+    #   response = DhanHQ::Models::PnlExit.stop
+    #   puts response[:pnl_exit_status] # => "DISABLED"
+    #
+    class PnlExit < BaseModel
+      HTTP_PATH = "/v2/pnlExit"
+
+      attributes :pnl_exit_status, :profit, :loss, :segments, :enable_kill_switch
+
+      class << self
+        ##
+        # Provides a shared instance of the PnlExit resource.
+        #
+        # @return [DhanHQ::Resources::PnlExit] The PnlExit resource client instance
+        def resource
+          @resource ||= DhanHQ::Resources::PnlExit.new
+        end
+
+        ##
+        # Configure automatic P&L-based position exit.
+        #
+        # When the defined profit or loss thresholds are breached during the trading day,
+        # all applicable positions are exited automatically.
+        #
+        # @param profit_value [Float] Profit threshold that triggers exit (e.g., 1500.0)
+        # @param loss_value [Float] Loss threshold that triggers exit (e.g., 500.0)
+        # @param product_type [Array<String>] Product types to apply. e.g., ["INTRADAY", "DELIVERY"]
+        # @param enable_kill_switch [Boolean] Whether to activate kill switch after exit
+        #
+        # @return [Hash{Symbol => String}] Response hash containing:
+        #   - **:pnl_exit_status** [String] "ACTIVE" on success
+        #   - **:message** [String] Confirmation message
+        #
+        # @example Configure with kill switch
+        #   DhanHQ::Models::PnlExit.configure(
+        #     profit_value: 2000.0,
+        #     loss_value: 1000.0,
+        #     product_type: ["INTRADAY"],
+        #     enable_kill_switch: true
+        #   )
+        #
+        def configure(profit_value:, loss_value:, product_type:, enable_kill_switch: false)
+          params = {
+            profitValue: profit_value.to_s,
+            lossValue: loss_value.to_s,
+            productType: product_type,
+            enableKillSwitch: enable_kill_switch
+          }
+          resource.configure(params)
+        end
+
+        ##
+        # Stop/disable the active P&L-based exit configuration.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing:
+        #   - **:pnl_exit_status** [String] "DISABLED"
+        #   - **:message** [String] Confirmation message
+        #
+        # @example Disable P&L exit
+        #   response = DhanHQ::Models::PnlExit.stop
+        #   puts response[:pnl_exit_status] # => "DISABLED"
+        #
+        def stop
+          resource.stop
+        end
+
+        ##
+        # Fetch the currently active P&L-based exit configuration.
+        #
+        # @return [PnlExit] PnlExit object with current configuration.
+        #   - **:pnl_exit_status** [String] "ACTIVE" or "DISABLED"
+        #   - **:profit** [String] Configured profit threshold
+        #   - **:loss** [String] Configured loss threshold
+        #   - **:segments** [Array<String>] Active product types
+        #   - **:enable_kill_switch** [Boolean] Whether kill switch is enabled
+        #
+        # @example Check configuration
+        #   config = DhanHQ::Models::PnlExit.status
+        #   if config.pnl_exit_status == "ACTIVE"
+        #     puts "P&L exit active: profit=₹#{config.profit}, loss=₹#{config.loss}"
+        #   end
+        #
+        def status
+          response = resource.status
+          return nil unless response.is_a?(Hash)
+
+          new(response, skip_validation: true)
+        end
+      end
+
+      ##
+      # No validation contract needed — server-side validation handles it.
+      #
+      # @return [nil]
+      # @api private
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/position.rb

@@ -205,6 +205,28 @@ module DhanHQ
           response = resource.convert(formatted_params)
           success_response?(response) ? response : DhanHQ::ErrorObject.new(response)
         end
+
+        ##
+        # Exits all active positions and cancels all open orders for the current trading day.
+        #
+        # This is a safety endpoint for emergency position closure. It sends a DELETE request
+        # to close all positions and cancel all pending orders in one call.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing operation result.
+        #   - **:status** [String] "SUCCESS" or "ERROR"
+        #   - **:message** [String] Description of the result
+        #
+        # @example Emergency exit all positions
+        #   response = DhanHQ::Models::Position.exit_all!
+        #   if response[:status] == "SUCCESS"
+        #     puts "✓ All positions exited and orders cancelled"
+        #   else
+        #     puts "✗ Failed: #{response[:message]}"
+        #   end
+        #
+        def exit_all!
+          resource.exit_all
+        end
       end
     end
   end

data/lib/DhanHQ/models/postback.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Utility model for parsing Dhan postback (webhook) payloads.
+    #
+    # Postback is a webhook mechanism where Dhan pushes order status updates to your
+    # configured URL. This model provides a convenient way to parse the incoming JSON
+    # payload into a typed, attribute-accessible object.
+    #
+    # @note Postback URL is configured in the Dhan web console when generating an access
+    #   token. It will NOT work with localhost or 127.0.0.1.
+    #
+    # @example Parse postback payload in a Rails controller
+    #   class DhanWebhooksController < ApplicationController
+    #     skip_before_action :verify_authenticity_token
+    #
+    #     def create
+    #       postback = DhanHQ::Models::Postback.parse(request.body.read)
+    #       case postback.order_status
+    #       when "TRADED"
+    #         handle_fill(postback)
+    #       when "REJECTED"
+    #         handle_rejection(postback)
+    #       end
+    #       head :ok
+    #     end
+    #   end
+    #
+    # @example Parse postback payload from a hash
+    #   postback = DhanHQ::Models::Postback.parse(params)
+    #   puts "Order #{postback.order_id} is now #{postback.order_status}"
+    #   puts "Filled: #{postback.filled_qty}/#{postback.quantity}"
+    #
+    class Postback < BaseModel
+      HTTP_PATH = nil # No API endpoint — postback is pushed to the user
+
+      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, :filled_qty, :algo_id
+
+      class << self
+        ##
+        # Parse a postback webhook payload into a Postback model instance.
+        #
+        # Accepts either a JSON string (from request body) or a Hash (from parsed params).
+        # Keys are normalized to snake_case automatically.
+        #
+        # @param payload [String, Hash] Raw JSON string or Hash from the webhook
+        #
+        # @return [Postback] Parsed Postback object with typed attributes
+        #
+        # @example From raw JSON string
+        #   postback = DhanHQ::Models::Postback.parse('{"orderId":"123","orderStatus":"TRADED"}')
+        #   puts postback.order_status # => "TRADED"
+        #
+        # @example From a hash
+        #   postback = DhanHQ::Models::Postback.parse(order_id: "123", order_status: "TRADED")
+        #   puts postback.order_id # => "123"
+        #
+        def parse(payload)
+          data = case payload
+                 when String
+                   JSON.parse(payload)
+                 when Hash
+                   payload
+                 else
+                   raise ArgumentError, "Expected String or Hash, got #{payload.class}"
+                 end
+
+          new(data, skip_validation: true)
+        end
+      end
+
+      ##
+      # Whether the order has been fully traded.
+      #
+      # @return [Boolean]
+      def traded?
+        order_status == "TRADED"
+      end
+
+      ##
+      # Whether the order was rejected.
+      #
+      # @return [Boolean]
+      def rejected?
+        order_status == "REJECTED"
+      end
+
+      ##
+      # Whether the order is still pending.
+      #
+      # @return [Boolean]
+      def pending?
+        order_status == "PENDING"
+      end
+
+      ##
+      # Whether the order was cancelled.
+      #
+      # @return [Boolean]
+      def cancelled?
+        order_status == "CANCELLED"
+      end
+
+      ##
+      # No validation contract — postback payloads are parsed as-is.
+      #
+      # @return [nil]
+      # @api private
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/token_response.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "time"
+
+module DhanHQ
+  module Models
+    # Represents a Dhan API token response with expiry tracking and validation.
+    #
+    # TokenResponse wraps the response from Dhan's token generation and renewal
+    # endpoints, providing convenient methods for checking token validity and
+    # determining when refresh is needed.
+    #
+    # @example From token generation
+    #   response = Auth.generate_access_token(
+    #     dhan_client_id: "123",
+    #     pin: "1234",
+    #     totp: "654321"
+    #   )
+    #   token = TokenResponse.new(response)
+    #   token.expired?       # => false
+    #   token.expires_in     # => 86400 (seconds)
+    #   token.needs_refresh? # => false
+    #
+    # @example Checking token status
+    #   if token.needs_refresh?(buffer_seconds: 600)
+    #     # Refresh token 10 minutes before expiry
+    #     new_token = Auth.renew_token(...)
+    #   end
+    #
+    # @attr_reader [String] client_id Dhan client ID
+    # @attr_reader [String] client_name Dhan client name
+    # @attr_reader [String] ucc Unique client code
+    # @attr_reader [Boolean] power_of_attorney POA status
+    # @attr_reader [String] access_token The authentication token
+    # @attr_reader [Time] expiry_time Token expiration timestamp
+    class TokenResponse
+      attr_reader :client_id,
+                  :client_name,
+                  :ucc,
+                  :power_of_attorney,
+                  :access_token,
+                  :expiry_time
+
+      def initialize(data)
+        data = normalize_keys(data)
+
+        @client_id = data["dhanClientId"]
+        @client_name = data["dhanClientName"]
+        @ucc = data["dhanClientUcc"]
+        @power_of_attorney = data["givenPowerOfAttorney"]
+        @access_token = data["accessToken"]
+        @expiry_time = parse_time(data["expiryTime"])
+      end
+
+      def expired?
+        return true unless expiry_time
+
+        Time.now >= expiry_time
+      end
+
+      def expires_in
+        return 0 unless expiry_time
+
+        expiry_time - Time.now
+      end
+
+      def needs_refresh?(buffer_seconds: 300)
+        return true unless expiry_time
+
+        Time.now >= (expiry_time - buffer_seconds)
+      end
+
+      private
+
+      def normalize_keys(data)
+        return {} unless data.is_a?(Hash)
+
+        data.transform_keys(&:to_s)
+      end
+
+      def parse_time(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        Time.parse(value.to_s)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/kill_switch.rb

@@ -16,6 +16,14 @@ module DhanHQ
       def update(params)
         post("", params: params)
       end
+
+      ##
+      # Fetches the current kill switch status.
+      #
+      # @return [Hash] API response containing dhan_client_id and kill_switch_status.
+      def status
+        get("")
+      end
     end
   end
 end

data/lib/DhanHQ/resources/margin_calculator.rb

@@ -17,6 +17,15 @@ module DhanHQ
       def calculate(params)
         post("", params: params)
       end
+
+      ##
+      # Calculate margin requirements for multiple scripts in one request.
+      #
+      # @param params [Hash] Request parameters including scripList, includePosition, includeOrder.
+      # @return [Hash] API response containing combined margin details with hedge benefit.
+      def calculate_multi(params)
+        post("/multi", params: params)
+      end
     end
   end
 end

data/lib/DhanHQ/resources/pnl_exit.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource for P&L Based Exit endpoints per https://dhanhq.co/docs/v2/traders-control/
+    # POST /v2/pnlExit — configure, DELETE /v2/pnlExit — stop, GET /v2/pnlExit — status.
+    class PnlExit < BaseAPI
+      API_TYPE  = :order_api
+      HTTP_PATH = "/v2/pnlExit"
+
+      ##
+      # Configure automatic P&L-based position exit.
+      #
+      # @param params [Hash] Request body with profitValue, lossValue, productType, enableKillSwitch.
+      # @return [Hash] API response containing pnlExitStatus and message.
+      def configure(params)
+        post("", params: params)
+      end
+
+      ##
+      # Stop/disable the active P&L-based exit configuration.
+      #
+      # @return [Hash] API response containing pnlExitStatus and message.
+      def stop
+        delete("")
+      end
+
+      ##
+      # Fetch the currently active P&L-based exit configuration.
+      #
+      # @return [Hash] API response containing pnlExitStatus, profit, loss, segments, enable_kill_switch.
+      def status
+        get("")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/positions.rb

@@ -24,6 +24,14 @@ module DhanHQ
       def convert(params)
         post("/convert", params: params)
       end
+
+      ##
+      # Exit all active positions and cancel all open orders.
+      #
+      # @return [Hash] API response containing status and message.
+      def exit_all
+        delete("")
+      end
     end
   end
 end

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "2.3.0"
+  VERSION = "2.5.0"
 end

data/lib/dhan_hq.rb

@@ -1,96 +1,46 @@
 # frozen_string_literal: true
 
-require "dotenv/load"
+require "json"
 require "logger"
-
-# Helper Methods
+require "zeitwerk"
+require "dotenv/load"
+# Minimal eager requires for backward-compatible constants.
+# These are widely referenced (e.g. `DhanHQ::BaseAPI`) and should not depend on
+# the autoloader being fully configured.
 require_relative "DhanHQ/helpers/api_helper"
 require_relative "DhanHQ/helpers/attribute_helper"
 require_relative "DhanHQ/helpers/validation_helper"
 require_relative "DhanHQ/helpers/request_helper"
 require_relative "DhanHQ/helpers/response_helper"
-require_relative "DhanHQ/json_loader"
-
 require_relative "DhanHQ/core/base_api"
-require_relative "DhanHQ/core/base_resource"
 require_relative "DhanHQ/core/base_model"
-require_relative "DhanHQ/core/error_handler"
-
-require_relative "DhanHQ/version"
-require_relative "DhanHQ/errors"
-require_relative "DhanHQ/error_object"
-
-require_relative "DhanHQ/client"
-require_relative "DhanHQ/configuration"
-require_relative "DhanHQ/rate_limiter"
-require_relative "DhanHQ/auth"
-
-# Contracts
-require_relative "DhanHQ/contracts/base_contract"
-require_relative "DhanHQ/contracts/historical_data_contract"
-require_relative "DhanHQ/contracts/margin_calculator_contract"
-require_relative "DhanHQ/contracts/position_conversion_contract"
-require_relative "DhanHQ/contracts/slice_order_contract"
-require_relative "DhanHQ/contracts/trade_contract"
-require_relative "DhanHQ/contracts/expired_options_data_contract"
-require_relative "DhanHQ/contracts/alert_order_contract"
-
-# Resources
-require_relative "DhanHQ/resources/option_chain"
-require_relative "DhanHQ/resources/orders"
-require_relative "DhanHQ/resources/forever_orders"
-require_relative "DhanHQ/resources/super_orders"
-require_relative "DhanHQ/resources/funds"
-require_relative "DhanHQ/resources/holdings"
-require_relative "DhanHQ/resources/positions"
-require_relative "DhanHQ/resources/statements"
-require_relative "DhanHQ/resources/trades"
-require_relative "DhanHQ/resources/historical_data"
-require_relative "DhanHQ/resources/margin_calculator"
-require_relative "DhanHQ/resources/market_feed"
-require_relative "DhanHQ/resources/instruments"
-require_relative "DhanHQ/resources/alert_orders"
-require_relative "DhanHQ/resources/edis"
-require_relative "DhanHQ/resources/ip_setup"
-require_relative "DhanHQ/resources/kill_switch"
-require_relative "DhanHQ/resources/trader_control"
-require_relative "DhanHQ/resources/profile"
-require_relative "DhanHQ/resources/expired_options_data"
-
-# Models
-require_relative "DhanHQ/models/alert_order"
-require_relative "DhanHQ/models/order"
-require_relative "DhanHQ/models/funds"
-require_relative "DhanHQ/models/option_chain"
-require_relative "DhanHQ/models/forever_order"
-require_relative "DhanHQ/models/super_order"
-require_relative "DhanHQ/models/historical_data"
-require_relative "DhanHQ/models/market_feed"
-require_relative "DhanHQ/models/instrument"
-require_relative "DhanHQ/models/position"
-require_relative "DhanHQ/models/holding"
-require_relative "DhanHQ/models/ledger_entry"
-require_relative "DhanHQ/models/trade"
-require_relative "DhanHQ/models/margin"
-require_relative "DhanHQ/models/kill_switch"
-require_relative "DhanHQ/models/profile"
-require_relative "DhanHQ/models/order_update"
-require_relative "DhanHQ/models/expired_options_data"
-
-require_relative "DhanHQ/constants"
-require_relative "DhanHQ/ws"
-require_relative "DhanHQ/ws/singleton_lock"
-require_relative "ta"
-require_relative "dhanhq/analysis/multi_timeframe_analyzer"
-require_relative "dhanhq/analysis/helpers/bias_aggregator"
-require_relative "dhanhq/analysis/helpers/moneyness_helper"
-require_relative "dhanhq/contracts/options_buying_advisor_contract"
-require_relative "dhanhq/analysis/options_buying_advisor"
+require_relative "DhanHQ/core/base_resource"
 
 # The top-level module for the DhanHQ client library.
 #
 # Provides configuration management for setting credentials and API-related settings.
 module DhanHQ
+  LOADER = Zeitwerk::Loader.new
+  LOADER.tag = "dhanhq"
+  LOADER.inflector.inflect(
+    "api_helper" => "APIHelper",
+    "auth_api" => "AuthAPI",
+    "base_api" => "BaseAPI",
+    "ip_setup" => "IPSetup",
+    "json_loader" => "JSONLoader",
+    "ws" => "WS"
+  )
+  LOADER.push_dir(File.join(__dir__, "DhanHQ"), namespace: self)
+  LOADER.push_dir(File.join(__dir__, "dhanhq"), namespace: self)
+  LOADER.collapse(File.join(__dir__, "DhanHQ", "core"))
+  LOADER.collapse(File.join(__dir__, "DhanHQ", "helpers"))
+  LOADER.collapse(File.join(__dir__, "dhanhq", "analysis", "helpers"))
+  LOADER.ignore(
+    File.join(__dir__, "DhanHQ", "errors.rb"),
+    File.join(__dir__, "DhanHQ", "version.rb")
+  )
+  LOADER.setup
+
   class Error < StandardError; end
 
   class << self
@@ -131,7 +81,7 @@ module DhanHQ
 
     # Configures the DhanHQ client using environment variables.
     #
-    # When credentials are injected via `ACCESS_TOKEN` and `CLIENT_ID` this helper
+    # When credentials are injected via `DHAN_ACCESS_TOKEN` and `DHAN_CLIENT_ID` this helper
     # can be used to initialise a configuration without a block.
     #
     # @example
@@ -140,8 +90,8 @@ module DhanHQ
     # @return [void]
     def configure_with_env
       self.configuration ||= Configuration.new
-      configuration.access_token = ENV.fetch("ACCESS_TOKEN", nil)
-      configuration.client_id = ENV.fetch("CLIENT_ID", nil)
+      configuration.access_token = ENV.fetch("DHAN_ACCESS_TOKEN", nil)
+      configuration.client_id = ENV.fetch("DHAN_CLIENT_ID", nil)
       configuration.base_url = ENV.fetch("DHAN_BASE_URL", BASE_URL)
       configuration.ws_version = ENV.fetch("DHAN_WS_VERSION", configuration.ws_version || 2).to_i
       configuration.ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", configuration.ws_order_url)