DhanHQ 2.3.0 → 2.5.0

data/docs/TROUBLESHOOTING.md

@@ -0,0 +1,117 @@
+# Troubleshooting
+
+Common issues and solutions when working with the DhanHQ Ruby client.
+
+---
+
+## 429: Unexpected Response Code
+
+**Symptom:** WebSocket connection fails with a 429 status.
+
+**Cause:** Too many connections opened in quick succession, or exceeding the per-user WebSocket connection limit (5 per user).
+
+**Solution:**
+- The client automatically cools off for **60 seconds** and retries with exponential backoff.
+- Prefer `ws.disconnect!` before reconnecting to cleanly release server-side resources.
+- Call `DhanHQ::WS.disconnect_all_local!` to kill any straggler connections.
+- Avoid rapid connect/disconnect loops — the client handles backoff internally.
+
+```ruby
+# Kill all local WebSocket connections
+DhanHQ::WS.disconnect_all_local!
+
+# Wait before reconnecting
+sleep(2)
+
+# Reconnect
+client = DhanHQ::WS.connect(mode: :ticker) { |tick| puts tick[:ltp] }
+```
+
+---
+
+## No Ticks After Reconnect
+
+**Symptom:** WebSocket reconnects successfully but no market data arrives.
+
+**Cause:** Subscriptions were not restored after the connection dropped.
+
+**Solution:**
+- The client **automatically resends** the current subscription snapshot on reconnect — this should work transparently.
+- If you're managing connections manually, ensure you re-subscribe after a clean start.
+- Check that your instruments are valid and the market is open.
+
+---
+
+## Binary Parse Errors
+
+**Symptom:** Errors in logs related to binary frame parsing.
+
+**Cause:** Malformed or unexpected binary frames from the server.
+
+**Solution:**
+- The client safely drops malformed frames and keeps the event loop alive.
+- Run with `DHAN_LOG_LEVEL=DEBUG` to inspect raw frames:
+
+```bash
+export DHAN_LOG_LEVEL=DEBUG
+```
+
+```ruby
+DhanHQ.logger.level = Logger::DEBUG
+```
+
+---
+
+## Authentication Errors
+
+| Error Class                          | Meaning                                                    |
+| ------------------------------------ | ---------------------------------------------------------- |
+| `DhanHQ::AuthenticationError`        | Token could not be resolved (missing config, nil provider) |
+| `DhanHQ::InvalidAuthenticationError` | API returned 401 or error code DH-901                      |
+| `DhanHQ::TokenExpiredError`          | API returned error code 807 (token expired)                |
+| `DhanHQ::InvalidTokenError`          | API returned error code 809 (invalid token)                |
+
+**Solutions:**
+- Verify `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` are set correctly.
+- If using `access_token_provider`, ensure it returns a non-nil string.
+- For 401 retries: the client retries **once** with a fresh token when `access_token_provider` is configured.
+- See [AUTHENTICATION.md](AUTHENTICATION.md) for detailed token lifecycle handling.
+
+---
+
+## Connection Timeouts
+
+**Symptom:** REST API calls hang or fail with timeout errors.
+
+**Solution:** Adjust timeout settings via environment variables:
+
+```dotenv
+DHAN_CONNECT_TIMEOUT=15   # default: 10 seconds
+DHAN_READ_TIMEOUT=60      # default: 30 seconds
+DHAN_WRITE_TIMEOUT=60     # default: 30 seconds
+```
+
+---
+
+## Debug Logging
+
+Enable full debug output to diagnose any issue:
+
+```ruby
+DhanHQ.logger.level = Logger::DEBUG
+```
+
+Or via environment:
+
+```bash
+export DHAN_LOG_LEVEL=DEBUG
+```
+
+This logs HTTP requests/responses, WebSocket frames, and internal state transitions.
+
+---
+
+## Getting Help
+
+- [DhanHQ GitHub Issues](https://github.com/shubhamtaywade82/dhanhq-client/issues)
+- [Dhan API Documentation](https://dhanhq.co/docs/v2/)

data/docs/WEBSOCKET_PROTOCOL.md

@@ -0,0 +1,154 @@
+# WebSocket Protocol Reference
+
+Low-level protocol details for the DhanHQ WebSocket market feed. For high-level usage, see the [WebSocket Integration Guide](websocket_integration.md).
+
+---
+
+## Subscription Modes
+
+| Mode      | What you get                              | Best for                        |
+| --------- | ----------------------------------------- | ------------------------------- |
+| `:ticker` | LTP + LTT                                | Lightweight price monitoring    |
+| `:quote`  | LTP + LTT + OHLCV + totals               | Most trading strategies         |
+| `:full`   | Quote + OI + best-5 depth (bid/ask)       | Order book analysis, depth-based strategies |
+
+---
+
+## Request Codes
+
+Per Dhan documentation:
+
+| Action       | Ticker | Quote | Full |
+| ------------ | ------ | ----- | ---- |
+| Subscribe    | 15     | 17    | 21   |
+| Unsubscribe  | 16     | 18    | 22   |
+| Disconnect   | 12     | 12    | 12   |
+
+---
+
+## Packet Parsing
+
+### Response Header (8 bytes)
+
+| Field                | Size   | Encoding | Description                   |
+| -------------------- | ------ | -------- | ----------------------------- |
+| `feed_response_code` | 1 byte | u8, BE   | Identifies the packet type    |
+| `message_length`     | 2 bytes| u16, BE  | Total message length in bytes |
+| `exchange_segment`   | 1 byte | u8, BE   | Exchange segment identifier   |
+| `security_id`        | 4 bytes| i32, LE  | Security identifier           |
+
+### Packet Types
+
+| Code | Type          | Fields                                                        |
+| ---- | ------------- | ------------------------------------------------------------- |
+| 1    | Index         | Surfaced as raw/misc unless documented                       |
+| 2    | Ticker        | `ltp`, `ltt`                                                 |
+| 4    | Quote         | `ltp`, `ltt`, `atp`, `volume`, totals, `day_*`               |
+| 5    | OI            | `open_interest`                                              |
+| 6    | Prev Close    | `prev_close`, `oi_prev`                                      |
+| 7    | Market Status | Raw/misc unless documented                                   |
+| 8    | Full          | Quote fields + `open_interest` + 5× depth (bid/ask)         |
+| 50   | Disconnect    | Reason code                                                  |
+
+---
+
+## Normalized Tick Schema
+
+All ticks are delivered as a Ruby Hash with consistent keys:
+
+```ruby
+{
+  kind: :quote,               # :ticker | :quote | :full | :oi | :prev_close | :misc
+  segment: "NSE_FNO",         # string enum
+  security_id: "12345",
+  ltp: 101.5,
+  ts:  1723791300,            # LTT epoch (sec) if present
+  vol: 123456,                # quote/full only
+  atp: 100.9,                 # quote/full only
+  day_open: 100.1,
+  day_high: 102.4,
+  day_low: 99.5,
+  day_close: nil,
+  oi: 987654,                 # full or OI packet
+  bid: 101.45,                # from depth (mode :full)
+  ask: 101.55                 # from depth (mode :full)
+}
+```
+
+---
+
+## Connection Limits & Behavior
+
+### Limits
+
+- **100 instruments** per subscribe/unsubscribe frame (auto-chunked by the client)
+- **5 WebSocket connections** per user (per Dhan)
+
+### Backoff & 429 Cool-Off
+
+- Exponential backoff with jitter on connection failure
+- Handshake **429** triggers a **60-second cool-off** before retry
+- The client handles this automatically — avoid manual rapid reconnect loops
+
+### Reconnect & Resubscribe
+
+- On reconnect, the client resends the **current subscription snapshot** (idempotent)
+- No manual re-subscribe needed after automatic reconnection
+
+### Graceful Shutdown
+
+- `ws.disconnect!` — sends broker disconnect code 12, prevents reconnects
+- `ws.stop` — hard stop (no broker message, just closes and halts loop)
+- `DhanHQ::WS.disconnect_all_local!` — kills all registered WS clients
+- An `at_exit` hook stops all registered clients to avoid leaked sockets
+
+---
+
+## Exchange Segment Enums
+
+Use these string enums in WebSocket `subscribe_*` calls and REST parameters:
+
+| Enum           | Exchange | Segment           |
+| -------------- | -------- | ----------------- |
+| `IDX_I`        | Index    | Index Value       |
+| `NSE_EQ`       | NSE      | Equity Cash       |
+| `NSE_FNO`      | NSE      | Futures & Options |
+| `NSE_CURRENCY` | NSE      | Currency          |
+| `BSE_EQ`       | BSE      | Equity Cash       |
+| `BSE_FNO`      | BSE      | Futures & Options |
+| `BSE_CURRENCY` | BSE      | Currency          |
+| `MCX_COMM`     | MCX      | Commodity         |
+
+---
+
+## Tick Access Patterns
+
+### Direct Handler
+
+```ruby
+ws.on(:tick) { |t| do_something_fast(t) }  # avoid heavy work here
+```
+
+### Shared TickCache (Recommended)
+
+```ruby
+# app/services/live/tick_cache.rb
+class TickCache
+  MAP = Concurrent::Map.new
+  def self.put(t)  = MAP["#{t[:segment]}:#{t[:security_id]}"] = t
+  def self.get(seg, sid) = MAP["#{seg}:#{sid}"]
+  def self.ltp(seg, sid) = get(seg, sid)&.dig(:ltp)
+end
+
+ws.on(:tick) { |t| TickCache.put(t) }
+ltp = TickCache.ltp("NSE_FNO", "12345")
+```
+
+### Filtered Callback
+
+```ruby
+def on_tick_for(ws, segment:, security_id:, &blk)
+  key = "#{segment}:#{security_id}"
+  ws.on(:tick) { |t| blk.call(t) if "#{t[:segment]}:#{t[:security_id]}" == key }
+end
+```

data/docs/live_order_updates.md

@@ -194,8 +194,8 @@ client.start
 ### Environment Variables
 ```bash
 # Required
-CLIENT_ID=your_client_id
-ACCESS_TOKEN=your_access_token
+DHAN_CLIENT_ID=your_client_id
+DHAN_ACCESS_TOKEN=your_access_token
 
 # Optional WebSocket settings
 DHAN_WS_ORDER_URL=wss://api-order-update.dhan.co

data/docs/rails_integration.md

@@ -29,8 +29,8 @@ boot successfully:
 
 | Variable | Description |
 | --- | --- |
-| `CLIENT_ID` | Dhan trading client id for the account you want to trade with. |
-| `ACCESS_TOKEN` | REST/WebSocket access token (regenerate via the Dhan console or APIs). |
+| `DHAN_CLIENT_ID` | Dhan trading client id for the account you want to trade with. |
+| `DHAN_ACCESS_TOKEN` | REST/WebSocket access token (regenerate via the Dhan console or APIs). |
 
 ```bash
 bin/rails credentials:edit
@@ -61,8 +61,8 @@ environment variables (Rails credentials can be copied into ENV on boot):
 require 'dhan_hq'
 
 if (creds = Rails.application.credentials.dig(:dhanhq))
-  ENV['CLIENT_ID']        ||= creds[:client_id]
-  ENV['ACCESS_TOKEN']     ||= creds[:access_token]
+  ENV['DHAN_CLIENT_ID']        ||= creds[:client_id]
+  ENV['DHAN_ACCESS_TOKEN']     ||= creds[:access_token]
   ENV['DHAN_LOG_LEVEL']   ||= creds[:log_level]&.upcase
   ENV['DHAN_BASE_URL']    ||= creds[:base_url]
   ENV['DHAN_WS_ORDER_URL'] ||= creds[:ws_order_url]
@@ -77,8 +77,8 @@ if (creds = Rails.application.credentials.dig(:dhanhq))
 end
 
 # fall back to traditional ENV variables when credentials are not defined
-ENV['CLIENT_ID']    ||= ENV.fetch('DHAN_CLIENT_ID', nil)
-ENV['ACCESS_TOKEN'] ||= ENV.fetch('DHAN_ACCESS_TOKEN', nil)
+ENV['DHAN_CLIENT_ID']    ||= ENV.fetch('DHAN_CLIENT_ID', nil)
+ENV['DHAN_ACCESS_TOKEN'] ||= ENV.fetch('DHAN_ACCESS_TOKEN', nil)
 
 DhanHQ.configure_with_env
 
@@ -108,7 +108,7 @@ initializer calls `DhanHQ.configure_with_env`.
 For token rotation without restarting the app (e.g. token stored in DB or refreshed via OAuth), use `access_token_provider` so the token is resolved at request time:
 
 ```ruby
-# config/initializers/dhanhq.rb (alternative to static ACCESS_TOKEN)
+# config/initializers/dhanhq.rb (alternative to static DHAN_ACCESS_TOKEN)
 DhanHQ.configure do |config|
   config.client_id = ENV["DHAN_CLIENT_ID"] || Rails.application.credentials.dig(:dhanhq, :client_id)
   config.access_token_provider = lambda do

data/docs/standalone_ruby_websocket_integration.md

@@ -31,8 +31,8 @@ require 'dhan_hq'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -59,8 +59,8 @@ market_client.stop
 
 ```bash
 # Set environment variables
-export CLIENT_ID="your_client_id"
-export ACCESS_TOKEN="your_access_token"
+export DHAN_CLIENT_ID="your_client_id"
+export DHAN_ACCESS_TOKEN="your_access_token"
 
 # Run the script
 ruby market_feed_script.rb
@@ -74,8 +74,8 @@ For dynamic token at request time use `config.access_token_provider`. For web-ge
 
 ```bash
 # Required
-export CLIENT_ID="your_client_id"
-export ACCESS_TOKEN="your_access_token"
+export DHAN_CLIENT_ID="your_client_id"
+export DHAN_ACCESS_TOKEN="your_access_token"
 
 # Optional
 export DHAN_WS_USER_TYPE="SELF"  # or "PARTNER"
@@ -132,8 +132,8 @@ require 'json'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -264,8 +264,8 @@ require 'json'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -394,8 +394,8 @@ require 'json'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -542,8 +542,8 @@ WorkingDirectory=/opt/dhanhq-market-feed
 ExecStart=/usr/bin/ruby market_feed_daemon.rb
 Restart=always
 RestartSec=10
-Environment=CLIENT_ID=your_client_id
-Environment=ACCESS_TOKEN=your_access_token
+Environment=DHAN_CLIENT_ID=your_client_id
+Environment=DHAN_ACCESS_TOKEN=your_access_token
 Environment=DHAN_WS_USER_TYPE=SELF
 
 [Install]
@@ -562,8 +562,8 @@ require 'fileutils'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -779,8 +779,8 @@ require 'json'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -1061,8 +1061,8 @@ require 'json'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 
@@ -1264,8 +1264,8 @@ end
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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"
   config.logger = logger
 end
@@ -1383,8 +1383,8 @@ require 'json'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/docs/technical_analysis.md

@@ -12,7 +12,7 @@ This guide explains how to use the technical analysis modules bundled with this
 
 ## Prerequisites
 
-- Environment variables set: `CLIENT_ID`, `ACCESS_TOKEN`
+- Environment variables set: `DHAN_CLIENT_ID`, `DHAN_ACCESS_TOKEN`
 - Optional indicator gems:
   - `gem install ruby-technical-analysis technical-analysis`
 

data/docs/websocket_integration.md

@@ -28,8 +28,8 @@ require 'dhan_hq'
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 # For dynamic token: use config.access_token_provider. For web-generated tokens, refresh with DhanHQ::Auth.renew_token. API key/Partner flows: implement in your app. See docs/AUTHENTICATION.md.
@@ -787,8 +787,8 @@ puts "Depth subscriptions: #{depth_client.subscriptions}"
 ```ruby
 # ✅ Good: Environment variables
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"]
-  config.access_token = ENV["ACCESS_TOKEN"]
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
 end
 
 # ❌ Bad: Hardcoded credentials

data/examples/comprehensive_websocket_examples.rb

@@ -12,8 +12,8 @@ require "dhan_hq"
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/examples/instrument_finder_test.rb

@@ -8,8 +8,8 @@ require "dhan_hq"
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/examples/market_depth_example.rb

@@ -10,8 +10,8 @@ require "dhan_hq"
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/examples/market_feed_example.rb

@@ -10,8 +10,8 @@ require "dhan_hq"
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/examples/order_update_example.rb

@@ -10,8 +10,8 @@ require "dhan_hq"
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/examples/trading_fields_example.rb

@@ -9,8 +9,8 @@ require "dhan_hq"
 
 # Configure DhanHQ
 DhanHQ.configure do |config|
-  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
-  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  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
 

data/lib/DhanHQ/auth/token_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Auth
+    # Backward-compatible wrapper for token generation.
+    # Delegates to module-level Auth.generate_access_token.
+    class TokenGenerator
+      def generate(dhan_client_id:, pin:, totp: nil, totp_secret: nil)
+        otp = resolve_totp(totp, totp_secret)
+
+        response = Auth.generate_access_token(
+          dhan_client_id: dhan_client_id,
+          pin: pin,
+          totp: otp
+        )
+
+        Models::TokenResponse.new(response)
+      end
+
+      private
+
+      def resolve_totp(totp, secret)
+        totp = totp.to_s.strip
+        return totp unless totp.empty?
+
+        secret = secret.to_s.strip
+        raise ArgumentError, "Provide `totp` or `totp_secret` (e.g. ENV['DHAN_TOTP_SECRET'])" if secret.empty?
+
+        Auth.generate_totp(secret)
+      end
+    end
+  end
+end

data/lib/DhanHQ/auth/token_manager.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module DhanHQ
+  module Auth
+    # Manages automatic token lifecycle including generation, renewal, and validation.
+    #
+    # TokenManager provides production-grade token automation by:
+    # - Generating new tokens via TOTP when needed
+    # - Renewing tokens before expiry (5-minute buffer)
+    # - Falling back to full generation if renewal fails
+    # - Thread-safe token operations via Monitor lock
+    #
+    # @example Enable auto token management
+    #   client = DhanHQ::Client.new(api_type: :order_api)
+    #   client.enable_auto_token_management!(
+    #     dhan_client_id: ENV["DHAN_CLIENT_ID"],
+    #     pin: ENV["DHAN_PIN"],
+    #     totp_secret: ENV["DHAN_TOTP_SECRET"]
+    #   )
+    #
+    # @example Manual usage
+    #   manager = TokenManager.new(
+    #     dhan_client_id: "123",
+    #     pin: "1234",
+    #     totp_secret: "SECRET"
+    #   )
+    #   manager.ensure_valid_token!  # Auto-generates or renews as needed
+    #
+    # @see Auth::TokenGenerator for TOTP-based token generation
+    # @see Auth::TokenRenewal for token renewal logic
+    class TokenManager
+      def initialize(dhan_client_id:, pin:, totp_secret:)
+        @dhan_client_id = dhan_client_id
+        @pin = pin
+        @totp_secret = totp_secret
+
+        @token = nil
+        @lock = Monitor.new
+      end
+
+      def generate!
+        @lock.synchronize do
+          token = Auth::TokenGenerator.new.generate(
+            dhan_client_id: @dhan_client_id,
+            pin: @pin,
+            totp_secret: @totp_secret
+          )
+
+          apply_token(token)
+        end
+      end
+
+      def ensure_valid_token!
+        return generate! unless @token
+
+        return unless @token.needs_refresh?
+
+        refresh!
+      end
+
+      def refresh!
+        @lock.synchronize do
+          return generate! unless @token
+
+          renewal = Auth::TokenRenewal.new.renew
+          apply_token(renewal)
+        rescue Errors::AuthenticationError
+          generate!
+        end
+      end
+
+      private
+
+      def apply_token(token)
+        @token = token
+
+        DhanHQ.configure do |config|
+          config.access_token = token.access_token
+          config.client_id = token.client_id if token.client_id.to_s.strip != ""
+        end
+
+        token
+      end
+    end
+  end
+end