DhanHQ 2.5.0 → 2.6.1

data/app/services/live/order_update_guard_support.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Live
-  # Guard-related helpers for interpreting order update payloads.
-  module OrderUpdateGuardSupport
-    module_function
-
-    SEGMENT_MAP = {
-      %w[NSE E] => "NSE_EQ",
-      %w[BSE E] => "BSE_EQ",
-      %w[NSE D] => "NSE_FNO",
-      %w[BSE D] => "BSE_FNO",
-      %w[NSE C] => "NSE_CURRENCY",
-      %w[BSE C] => "BSE_CURRENCY",
-      %w[MCX M] => "MCX_COMM"
-    }.freeze
-
-    DEFAULT_SL_PCT    = 0.15
-    DEFAULT_TP_PCT    = 0.30
-    DEFAULT_TRAIL_PCT = 0.01
-
-    def map_segment(exchange, segment)
-      key = [exchange.to_s.upcase, segment.to_s.upcase]
-      SEGMENT_MAP.fetch(key, "NSE_EQ")
-    end
-
-    def position_guard_payload(segment, security_id, order_data)
-      guard_base_payload(segment, security_id, order_data)
-        .merge(guard_percentage_payload(segment, security_id))
-    end
-
-    def guard_base_payload(segment, security_id, order_data)
-      {
-        pos_id: nil,
-        exchange_segment: segment,
-        security_id: security_id,
-        entry: average_entry(order_data),
-        qty: order_data[:TradedQty].to_i,
-        placed_as: placed_as(order_data),
-        super_order_id: order_data[:OrderNo].to_s
-      }
-    end
-
-    def guard_percentage_payload(segment, security_id)
-      {
-        sl_pct: default_sl_pct(segment, security_id),
-        tp_pct: default_tp_pct(segment, security_id),
-        trail_pct: default_trail_pct(segment, security_id)
-      }
-    end
-
-    def placed_as(order_data)
-      order_data[:Remarks].to_s.match?(/Super Order/i) ? "super" : "plain"
-    end
-
-    def average_entry(order_data)
-      first_price = [order_data[:AvgTradedPrice], order_data[:TradedPrice], order_data[:Price]]
-                    .compact
-                    .first
-      first_price.to_f
-    end
-
-    def default_sl_pct(_segment, _security_id)
-      DEFAULT_SL_PCT
-    end
-
-    def default_tp_pct(_segment, _security_id)
-      DEFAULT_TP_PCT
-    end
-
-    def default_trail_pct(_segment, _security_id)
-      DEFAULT_TRAIL_PCT
-    end
-  end
-end

data/app/services/live/order_update_hub.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-require "singleton"
-require_relative "order_update_guard_support"
-require_relative "order_update_persistence_support"
-
-module Live
-  # OrderUpdateHub listens for order updates over WebSocket and wires them into
-  # local persistence plus downstream execution helpers.
-  class OrderUpdateHub
-    include Singleton
-
-    def start!
-      return self if @started
-
-      @client = DhanHQ::WS::Orders::Client.new.start
-      @client.on(:update) { |msg| handle(msg) }
-      @started = true
-      self
-    end
-
-    def stop!
-      @client&.stop
-      @started = false
-    end
-
-    private
-
-    def handle(message)
-      return unless order_alert?(message)
-
-      order_data = message[:Data] || {}
-      upsert_local_order(order_data)
-      handle_entry_leg(order_data)
-    rescue StandardError => e
-      Rails.logger.error("[OrderUpdateHub] #{e.class}: #{e.message}")
-    end
-
-    def order_alert?(message)
-      message&.dig(:Type) == "order_alert"
-    end
-
-    def handle_entry_leg(order_data)
-      return unless entry_leg_traded?(order_data)
-
-      segment = OrderUpdateGuardSupport.map_segment(order_data[:Exchange], order_data[:Segment])
-      security_id = order_data[:SecurityId].to_s
-      Live::WsHub.instance.subscribe(seg: segment, sid: security_id) if defined?(Live::WsHub)
-
-      register_position_guard(segment, security_id, order_data)
-    end
-
-    def register_position_guard(segment, security_id, order_data)
-      return unless defined?(Execution::PositionGuard)
-
-      payload = OrderUpdateGuardSupport.position_guard_payload(segment, security_id, order_data)
-      Execution::PositionGuard.instance.register(**payload)
-    end
-
-    def upsert_local_order(order_data)
-      order_number = order_data[:OrderNo].to_s
-      record = BrokerOrder.find_or_initialize_by(order_no: order_number)
-      attributes = OrderUpdatePersistenceSupport.local_order_attributes(order_data)
-      record.assign_attributes(attributes)
-      record.save!
-    rescue NameError
-      nil
-    end
-
-    def entry_leg_traded?(order_data)
-      order_data[:LegNo].to_i == 1 &&
-        order_data[:Status].to_s.upcase == "TRADED" &&
-        order_data[:TradedQty].to_i.positive?
-    end
-  end
-end

data/app/services/live/order_update_persistence_support.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-require "bigdecimal"
-
-module Live
-  # Persistence helper routines for order update payloads.
-  module OrderUpdatePersistenceSupport
-    module_function
-
-    def local_order_attributes(order_data)
-      identity_attributes(order_data)
-        .merge(quantity_attributes(order_data))
-        .merge(price_attributes(order_data))
-        .merge(timestamp_attributes(order_data))
-    end
-
-    def identity_attributes(order_data)
-      {
-        exch_order_no: order_data[:ExchOrderNo].to_s,
-        status: order_data[:Status],
-        product: order_data[:ProductName] || order_data[:Product],
-        txn_type: order_data[:TxnType],
-        order_type: order_data[:OrderType]
-      }
-    end
-
-    def quantity_attributes(order_data)
-      {
-        validity: order_data[:Validity],
-        exchange: order_data[:Exchange],
-        segment: order_data[:Segment],
-        security_id: order_data[:SecurityId].to_s,
-        quantity: order_data[:Quantity].to_i,
-        traded_qty: order_data[:TradedQty].to_i
-      }
-    end
-
-    def price_attributes(order_data)
-      {
-        price: decimal(order_data[:Price]),
-        trigger_price: decimal(order_data[:TriggerPrice]),
-        traded_price: decimal(order_data[:TradedPrice]),
-        avg_traded_price: decimal(order_data[:AvgTradedPrice])
-      }
-    end
-
-    def timestamp_attributes(order_data)
-      {
-        last_update_at: parse_timestamp(order_data[:LastUpdatedTime]),
-        raw_payload: order_data
-      }
-    end
-
-    def decimal(value)
-      return BigDecimal(0) if value.nil?
-
-      BigDecimal(value.to_s)
-    end
-
-    def parse_timestamp(timestamp)
-      return nil if timestamp.nil? || timestamp == ""
-
-      Time.zone.parse(timestamp)
-    rescue StandardError
-      nil
-    end
-  end
-end

data/docs/PR_2.2.0.md

@@ -1,48 +0,0 @@
-# PR: Dynamic access token resolution, auto-expiry detection, retry-on-401
-
-## Summary
-
-Adds production-grade auth handling to `dhanhq-client`:
-
-1. **Dynamic access token resolution** — Token can come from a callable (`access_token_provider`) at request time.
-2. **Auto-expiry detection** — API error code 807 (token expired) raises `DhanHQ::TokenExpiredError`.
-3. **Retry-on-401 with token re-fetch** — On 401/token-expired, if `access_token_provider` is set, the client retries once; the next request calls the provider again for a fresh token.
-4. **Optional `on_token_expired` hook** — Invoked before retry when auth failure triggers a retry (e.g. for logging or refreshing token in your store).
-
-## Changes
-
-- **Configuration**: `access_token_provider`, `on_token_expired`, `resolved_access_token`.
-- **Errors**: `DhanHQ::AuthenticationError` (local token resolution failure), `DhanHQ::TokenExpiredError` (API 807).
-- **Client**: Retry-on-401 for `InvalidAuthenticationError`, `InvalidTokenError`, `TokenExpiredError`, `AuthenticationFailedError` when provider is set (single retry).
-- **REST + WebSocket**: All token usage goes through `config.resolved_access_token` (no memoization).
-
-## Backward compatibility
-
-- **Non-breaking**. Existing `config.access_token = "static-token"` still works. `access_token_provider` is optional. Safe as a **minor** version bump (2.2.0).
-
-## Testing
-
-- `spec/dhan_hq/configuration_spec.rb` — `#resolved_access_token` (provider, fallback, nil/empty).
-- `spec/dhan_hq/client_spec.rb` — WebMock: 401, 403, 807, retry-on-401 success, retry then raise, `on_token_expired` hook.
-- `spec/dhan_hq/helpers/response_helper_spec.rb` — 807 → TokenExpiredError.
-
-## Changelog
-
-See [CHANGELOG.md](../CHANGELOG.md) — section **## [2.2.0] - 2026-01-31**.
-
-## README & docs
-
-- **README.md**: New subsection “Dynamic access token (optional)” under Configuration (access_token_provider, on_token_expired, retry-on-401, AuthenticationError / TokenExpiredError).
-- **GUIDE.md**: Short “Dynamic access token” note and link to docs/AUTHENTICATION.md.
-- **docs/AUTHENTICATION.md**: New doc for static vs dynamic token, retry-on-401, and auth-related errors.
-- **docs/TESTING_GUIDE.md**: Optional access_token_provider / on_token_expired in config examples; verify “Token provider” in console.
-- **docs/rails_integration.md**: New “Dynamic access token (optional)” with Rails initializer example.
-- **docs/websocket_integration.md**, **docs/live_order_updates.md**: One-line pointer to docs/AUTHENTICATION.md for dynamic token.
-
-## Checklist
-
-- [x] All specs pass
-- [x] No breaking changes
-- [x] CHANGELOG updated
-- [x] Version bumped to 2.2.0
-- [x] README and docs updated

data/examples/comprehensive_websocket_examples.rb

@@ -1,148 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Comprehensive WebSocket Examples
-# This script demonstrates all three DhanHQ WebSocket types:
-# 1. Market Feed WebSocket - Real-time market data
-# 2. Order Update WebSocket - Real-time order updates
-# 3. Market Depth WebSocket - Real-time market depth
-# NOTE: Uses sequential connections to avoid rate limiting
-
-require "dhan_hq"
-
-# Configure DhanHQ
-DhanHQ.configure do |config|
-  config.client_id = ENV["DHAN_CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["DHAN_ACCESS_TOKEN"] || "your_access_token"
-  config.ws_user_type = ENV["DHAN_WS_USER_TYPE"] || "SELF"
-end
-
-puts "DhanHQ Comprehensive WebSocket Examples"
-puts "======================================="
-puts "Demonstrates all three WebSocket types:"
-puts "1. Market Feed - Real-time market data for indices"
-puts "2. Order Update - Real-time order status updates"
-puts "3. Market Depth - Real-time bid/ask levels"
-puts ""
-puts "NOTE: Uses sequential connections to avoid rate limiting (429 errors)"
-puts "Dhan allows up to 5 WebSocket connections per user"
-puts ""
-
-# Example 1: Market Feed WebSocket
-puts "1. Market Feed WebSocket Example"
-puts "================================"
-
-puts "Creating Market Feed WebSocket connection..."
-market_client = DhanHQ::WS.connect(mode: :ticker) do |tick|
-  timestamp = tick[:ts] ? Time.at(tick[:ts]) : Time.now
-  puts "Market Data: #{tick[:segment]}:#{tick[:security_id]} = #{tick[:ltp]} at #{timestamp}"
-end
-
-# Subscribe to major Indian indices
-puts "\nSubscribing to major Indian indices:"
-puts "- Security ID 13: NIFTY (Nifty 50)"
-puts "- Security ID 25: BANKNIFTY (Nifty Bank)"
-puts "- Security ID 29: NIFTYIT (Nifty IT)"
-puts "- Security ID 51: SENSEX (Sensex)"
-
-market_client.subscribe_one(segment: "IDX_I", security_id: "13")  # NIFTY
-market_client.subscribe_one(segment: "IDX_I", security_id: "25")  # BANKNIFTY
-market_client.subscribe_one(segment: "IDX_I", security_id: "29")  # NIFTYIT
-market_client.subscribe_one(segment: "IDX_I", security_id: "51")  # SENSEX
-
-puts "\nMarket Feed WebSocket connected successfully!"
-puts "Waiting 10 seconds to receive market data..."
-sleep(10)
-
-puts "Stopping Market Feed WebSocket to prevent rate limiting..."
-market_client.stop
-sleep(2)
-
-# Example 2: Order Update WebSocket
-puts "\n2. Order Update WebSocket Example"
-puts "=================================="
-
-puts "Creating Order Update WebSocket connection..."
-orders_client = DhanHQ::WS::Orders.connect do |order_update|
-  puts "Order Update: #{order_update.order_no} - #{order_update.status}"
-  puts "  Symbol: #{order_update.symbol}"
-  puts "  Quantity: #{order_update.quantity}"
-  puts "  Traded Qty: #{order_update.traded_qty}"
-  puts "  Price: #{order_update.price}"
-  puts "  Execution: #{order_update.execution_percentage}%"
-  puts "  ---"
-end
-
-# Add event handlers
-orders_client.on(:update) { |order| puts "📝 Order Updated: #{order.order_no}" }
-orders_client.on(:execution) { |exec| puts "✅ Execution: #{exec[:new_traded_qty]} shares" }
-orders_client.on(:order_rejected) { |order| puts "❌ Order Rejected: #{order.order_no}" }
-
-puts "\nOrder Update WebSocket connected successfully!"
-puts "Waiting 10 seconds to receive order updates..."
-sleep(10)
-
-puts "Stopping Order Update WebSocket to prevent rate limiting..."
-orders_client.stop
-sleep(2)
-
-# Example 3: Market Depth WebSocket
-puts "\n3. Market Depth WebSocket Example"
-puts "=================================="
-
-puts "Creating Market Depth WebSocket connection..."
-
-# Find instruments using the new .find method (now uses underlying_symbol for equity)
-reliance_instrument = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
-tcs_instrument = DhanHQ::Models::Instrument.find("NSE_EQ", "TCS")
-
-# Define symbols with correct exchange segments and security IDs
-symbols = []
-if reliance_instrument
-  symbols << { symbol: "RELIANCE", exchange_segment: reliance_instrument.exchange_segment,
-               security_id: reliance_instrument.security_id }
-  puts "✅ Found RELIANCE: #{reliance_instrument.symbol_name} (#{reliance_instrument.exchange_segment}:#{reliance_instrument.security_id})"
-end
-
-if tcs_instrument
-  symbols << { symbol: "TCS", exchange_segment: tcs_instrument.exchange_segment,
-               security_id: tcs_instrument.security_id }
-  puts "✅ Found TCS: #{tcs_instrument.symbol_name} (#{tcs_instrument.exchange_segment}:#{tcs_instrument.security_id})"
-end
-
-depth_client = DhanHQ::WS::MarketDepth.connect(symbols: symbols) do |depth_data|
-  puts "Market Depth: #{depth_data[:symbol]}"
-  puts "  Best Bid: #{depth_data[:best_bid]}"
-  puts "  Best Ask: #{depth_data[:best_ask]}"
-  puts "  Spread: #{depth_data[:spread]}"
-  puts "  Bid Levels: #{depth_data[:bids].size}"
-  puts "  Ask Levels: #{depth_data[:asks].size}"
-  puts "  ---"
-end
-
-puts "\nMarket Depth WebSocket connected successfully!"
-puts "Waiting 10 seconds to receive market depth data..."
-sleep(10)
-
-puts "Stopping Market Depth WebSocket to prevent rate limiting..."
-depth_client.stop
-sleep(2)
-
-# Final cleanup
-puts "\n4. Final Cleanup"
-puts "================"
-
-puts "Ensuring all WebSocket connections are closed..."
-DhanHQ::WS.disconnect_all_local!
-
-puts "\nAll WebSocket connections closed."
-puts "Comprehensive example completed!"
-puts ""
-puts "Summary:"
-puts "- Successfully demonstrated all three WebSocket types:"
-puts "  * Market Feed: Real-time index data (NIFTY, BANKNIFTY, NIFTYIT, SENSEX)"
-puts "  * Order Update: Real-time order status tracking"
-puts "  * Market Depth: Real-time bid/ask levels (RELIANCE, TCS) - dynamically resolved"
-puts "- Used sequential connections to avoid rate limiting (429 errors)"
-puts "- Proper connection cleanup prevents resource leaks"
-puts "- No multiple connection issues!"

data/examples/instrument_finder_test.rb

@@ -1,195 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Test script for the new DhanHQ::Models::Instrument.find method
-# This script demonstrates how to use the new .find and .find_anywhere methods
-
-require "dhan_hq"
-
-# Configure DhanHQ
-DhanHQ.configure do |config|
-  config.client_id = ENV["DHAN_CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["DHAN_ACCESS_TOKEN"] || "your_access_token"
-  config.ws_user_type = ENV["DHAN_WS_USER_TYPE"] || "SELF"
-end
-
-puts "DhanHQ Instrument Finder Test"
-puts "============================="
-puts "Testing the new .find and .find_anywhere methods"
-puts ""
-
-# Test 1: Find specific instruments in known segments
-puts "1. Finding instruments in specific segments:"
-puts "-" * 40
-
-# Find RELIANCE in NSE_EQ (now uses underlying_symbol for equity)
-reliance = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
-if reliance
-  puts "✅ RELIANCE:"
-  puts "   Symbol Name: #{reliance.symbol_name}"
-  puts "   Underlying Symbol: #{reliance.underlying_symbol}"
-  puts "   Security ID: #{reliance.security_id}"
-  puts "   Display Name: #{reliance.display_name}"
-  puts "   Exchange Segment: #{reliance.exchange_segment}"
-else
-  puts "❌ RELIANCE not found"
-end
-
-puts
-
-# Find TCS in NSE_EQ (now uses underlying_symbol for equity)
-tcs = DhanHQ::Models::Instrument.find("NSE_EQ", "TCS")
-if tcs
-  puts "✅ TCS:"
-  puts "   Symbol Name: #{tcs.symbol_name}"
-  puts "   Underlying Symbol: #{tcs.underlying_symbol}"
-  puts "   Security ID: #{tcs.security_id}"
-  puts "   Display Name: #{tcs.display_name}"
-  puts "   Exchange Segment: #{tcs.exchange_segment}"
-else
-  puts "❌ TCS not found"
-end
-
-puts
-
-# Find NIFTY in IDX_I
-nifty = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
-if nifty
-  puts "✅ NIFTY:"
-  puts "   Security ID: #{nifty.security_id}"
-  puts "   Display Name: #{nifty.display_name}"
-  puts "   Exchange Segment: #{nifty.exchange_segment}"
-else
-  puts "❌ NIFTY not found"
-end
-
-puts
-
-# Find BANKNIFTY in IDX_I
-banknifty = DhanHQ::Models::Instrument.find("IDX_I", "BANKNIFTY")
-if banknifty
-  puts "✅ BANKNIFTY:"
-  puts "   Security ID: #{banknifty.security_id}"
-  puts "   Display Name: #{banknifty.display_name}"
-  puts "   Exchange Segment: #{banknifty.exchange_segment}"
-else
-  puts "❌ BANKNIFTY not found"
-end
-
-puts
-
-# Test 2: Find instruments anywhere (cross-segment search)
-puts "2. Finding instruments anywhere (cross-segment search):"
-puts "-" * 50
-
-# Find RELIANCE anywhere (now uses underlying_symbol for equity)
-reliance_anywhere = DhanHQ::Models::Instrument.find_anywhere("RELIANCE", exact_match: true)
-if reliance_anywhere
-  puts "✅ RELIANCE found anywhere:"
-  puts "   Symbol Name: #{reliance_anywhere.symbol_name}"
-  puts "   Underlying Symbol: #{reliance_anywhere.underlying_symbol}"
-  puts "   Security ID: #{reliance_anywhere.security_id}"
-  puts "   Display Name: #{reliance_anywhere.display_name}"
-  puts "   Exchange Segment: #{reliance_anywhere.exchange_segment}"
-else
-  puts "❌ RELIANCE not found anywhere"
-end
-
-puts
-
-# Find TCS anywhere (now uses underlying_symbol for equity)
-tcs_anywhere = DhanHQ::Models::Instrument.find_anywhere("TCS", exact_match: true)
-if tcs_anywhere
-  puts "✅ TCS found anywhere:"
-  puts "   Symbol Name: #{tcs_anywhere.symbol_name}"
-  puts "   Underlying Symbol: #{tcs_anywhere.underlying_symbol}"
-  puts "   Security ID: #{tcs_anywhere.security_id}"
-  puts "   Display Name: #{tcs_anywhere.display_name}"
-  puts "   Exchange Segment: #{tcs_anywhere.exchange_segment}"
-else
-  puts "❌ TCS not found anywhere"
-end
-
-puts
-
-# Find NIFTY anywhere
-nifty_anywhere = DhanHQ::Models::Instrument.find_anywhere("NIFTY", exact_match: true)
-if nifty_anywhere
-  puts "✅ NIFTY found anywhere:"
-  puts "   Security ID: #{nifty_anywhere.security_id}"
-  puts "   Display Name: #{nifty_anywhere.display_name}"
-  puts "   Exchange Segment: #{nifty_anywhere.exchange_segment}"
-else
-  puts "❌ NIFTY not found anywhere"
-end
-
-puts
-
-# Test 3: Advanced search options
-puts "3. Testing advanced search options:"
-puts "-" * 35
-
-# Test partial match
-reliance_partial = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
-if reliance_partial
-  puts "✅ RELIANCE (partial match):"
-  puts "   Symbol: #{reliance_partial.symbol_name}"
-  puts "   Security ID: #{reliance_partial.security_id}"
-else
-  puts "❌ RELIANCE (partial match) not found"
-end
-
-puts
-
-# Test case insensitive search
-reliance_case = DhanHQ::Models::Instrument.find("NSE_EQ", "reliance industries ltd", case_sensitive: false)
-if reliance_case
-  puts "✅ RELIANCE (case insensitive):"
-  puts "   Symbol: #{reliance_case.symbol_name}"
-  puts "   Security ID: #{reliance_case.security_id}"
-else
-  puts "❌ RELIANCE (case insensitive) not found"
-end
-
-puts
-
-# Test 4: Practical usage for WebSocket subscriptions
-puts "4. Practical usage for WebSocket subscriptions:"
-puts "-" * 45
-
-# Find instruments for Market Depth WebSocket
-puts "Finding instruments for Market Depth WebSocket:"
-
-market_depth_symbols = []
-symbols_to_find = [
-  { segment: "NSE_EQ", symbol: "RELIANCE", name: "RELIANCE" },
-  { segment: "NSE_EQ", symbol: "TCS", name: "TCS" }
-]
-
-symbols_to_find.each do |search|
-  instrument = DhanHQ::Models::Instrument.find(search[:segment], search[:symbol])
-  if instrument
-    market_depth_symbols << {
-      symbol: search[:name],
-      exchange_segment: instrument.exchange_segment,
-      security_id: instrument.security_id
-    }
-    puts "✅ #{search[:name]}: #{instrument.exchange_segment}:#{instrument.security_id}"
-  else
-    puts "❌ #{search[:name]}: Not found"
-  end
-end
-
-puts
-puts "Market Depth WebSocket symbols array:"
-puts market_depth_symbols.inspect
-
-puts
-puts "Test completed!"
-puts "==============="
-puts "The new .find and .find_anywhere methods make it easy to:"
-puts "- Find instruments by exchange segment and symbol"
-puts "- Search across multiple segments"
-puts "- Use exact or partial matching"
-puts "- Perform case-sensitive or case-insensitive searches"
-puts "- Dynamically resolve symbols for WebSocket subscriptions"