DhanHQ 2.3.0 → 2.5.0

data/REVIEW_SUMMARY.md

@@ -1,6 +1,6 @@
 # DhanHQ Client Gem - Review Summary
 
-**API Documentation**: https://api.dhan.co/v2/#/  
+**API Documentation**: https://api.dhan.co/v2/#/
 **Review Date**: 2025-01-27
 
 ## 🚨 Top 10 Critical Issues
@@ -15,7 +15,7 @@
 - **File**: `lib/DhanHQ/client.rb:40`
 - **Issue**: Partial configuration can lead to runtime authentication failures
 - **Impact**: Silent failures, difficult debugging
-- **Fix**: Validate both `CLIENT_ID` and `ACCESS_TOKEN` before proceeding
+- **Fix**: Validate both `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` before proceeding
 
 ### 3. **Memory Leak in Order Tracker** (HIGH)
 - **File**: `lib/DhanHQ/ws/orders/client.rb:18`

data/{README1.md → docs/ARCHIVE_README.md}

@@ -45,8 +45,8 @@ DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Lo
 
 **Minimum environment variables**
 
-* `CLIENT_ID` – trading account client id issued by Dhan.
-* `ACCESS_TOKEN` – API access token generated from the Dhan console.
+* `DHAN_CLIENT_ID` – trading account client id issued by Dhan.
+* `DHAN_ACCESS_TOKEN` – API access token generated from the Dhan console.
 
 If either key is missing `configure_with_env` raises an error. Ensure your
 application loads them into `ENV` before requiring the gem.
@@ -64,8 +64,8 @@ Create a `.env` file in your project root to supply the minimum values (and any
 optional overrides you need):
 
 ```dotenv
-CLIENT_ID=your_client_id
-ACCESS_TOKEN=your_access_token
+DHAN_CLIENT_ID=your_client_id
+DHAN_ACCESS_TOKEN=your_access_token
 ```
 
 The gem requires `dotenv/load`, so these variables are loaded automatically when you require `DhanHQ`.

data/docs/AUTHENTICATION.md

@@ -23,7 +23,7 @@ Set `access_token` once; it is sent on every request:
 ```ruby
 DhanHQ.configure do |config|
   config.client_id = ENV["DHAN_CLIENT_ID"]
-  config.access_token = ENV["ACCESS_TOKEN"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
 end
 ```
 
@@ -68,7 +68,7 @@ Example: refresh in provider and cache the result until near expiry:
 config.access_token_provider = lambda do
   stored = YourTokenStore.current
   if stored.nil? || stored.expired_soon?
-    response = DhanHQ::Auth.renew_token(stored&.access_token || ENV["ACCESS_TOKEN"], config.client_id)
+    response = DhanHQ::Auth.renew_token(stored&.access_token || ENV["DHAN_ACCESS_TOKEN"], config.client_id)
     YourTokenStore.update!(response["accessToken"], response["expiryTime"])
     stored = YourTokenStore.current
   end
@@ -108,3 +108,117 @@ Rescue `AuthenticationError` for local config/token resolution failures; rescue
 - [rails_integration.md](rails_integration.md) — Rails initializer with optional `access_token_provider` and RenewToken
 - [TESTING_GUIDE.md](TESTING_GUIDE.md) — Config examples and RenewToken
 - [CHANGELOG.md](../CHANGELOG.md) — 2.2.0 and 2.2.1 auth and token changes
+
+
+# SUPPORTED AUTHENTICATION AND TOKEN GENERATION APPROACHES:
+
+We now support five distinct authentication approaches in this gem.
+
+1️⃣ Static token (manual, simplest)
+What: You paste a token you got from Dhan (web, OAuth, partner, whatever) into config.
+How:
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
+```
+When: You’re OK rotating tokens manually (e.g. cron job, ops runbook).
+
+2️⃣ Dynamic token via access_token_provider
+What: Gem asks you for a token on every request (proc/lambda).
+How:
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token_provider = -> { MyTokenStore.fetch_current_token }
+  config.on_token_expired = ->(error) { MyTokenStore.refresh!(error) }
+end
+```
+Behavior:
+On 401 (auth failure), client calls on_token_expired, then retries once using a fresh token from access_token_provider.
+
+3️⃣ Fetch-from-token-endpoint (configure_from_token_endpoint)
+What: Gem calls your HTTP endpoint once to get access_token + client_id.
+How:
+```ruby
+DhanHQ.configure_from_token_endpoint(
+  base_url:    "https://myapp.com",
+  bearer_token: ENV["DHAN_TOKEN_ENDPOINT_BEARER"]
+)
+# expects JSON: { access_token: "...", client_id: "...", base_url: "..." (optional) }
+```
+When: Multi-tenant or central credential service, you don’t want tokens in ENV directly.
+
+4️⃣ TOTP-based token generation (new DhanHQ::Auth flow)
+Module API (low-level)
+What: Direct call to Dhan’s generateAccessToken endpoint using TOTP.
+```ruby
+totp = DhanHQ::Auth.generate_totp(ENV["DHAN_TOTP_SECRET"])
+response = DhanHQ::Auth.generate_access_token(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp:          totp
+)
+token  = response["accessToken"]
+expiry = response["expiryTime"]
+```
+
+Client API (high-level, returns TokenResponse)
+```
+client = DhanHQ::Client.new(api_type: :order_api)
+token = client.generate_access_token(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp_secret:   ENV["DHAN_TOTP_SECRET"] # or `totp:` if you computed it
+)
+# auto-applies token + client_id to `DhanHQ.configuration`
+```
+
+When: Fully automated individual setup (no manual web token generation).
+
+5️⃣ Auto token lifecycle management (TokenManager)
+What: Gem handles generate + renew + retry around every API call.
+How:
+```ruby
+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"]
+)
+# From now on, `client.request` auto-ensures a valid token.
+```
+Behavior:
+On first use: calls TOTP TokenGenerator → applies token.
+Before each request: ensure_valid_token!:
+If no token → generate.
+If needs_refresh? → TokenRenewal (POST /v2/RenewToken) with current token + dhanClientId.
+If renewal fails with auth error → falls back to full generate.
+
+6️⃣ Web-token renewal only (RenewToken)
+Module API:
+```ruby
+response = DhanHQ::Auth.renew_token(
+  access_token: current_token,
+  client_id:    ENV["DHAN_CLIENT_ID"]
+)
+```
+Client / manager (high-level):
+
+`client.renew_access_token` (returns TokenResponse, updates config).
+`TokenManager#refresh!` internally uses Auth::TokenRenewal.
+When: You’re using web-generated 24h tokens and want to extend them without switching to TOTP.
+
+TL;DR
+Manual: Static token (access_token)
+
+Dynamic: access_token_provider (+ optional on_token_expired)
+
+Central service: configure_from_token_endpoint
+
+Fully automated: TOTP generate (Auth / Client#generate_access_token)
+
+Production-grade automation: enable_auto_token_management! (generate + renew)
+
+If you tell me your exact deployment style (single user box, multi-user SaaS, on-prem, etc.), I can tell you which one you should actually use and what to delete as overkill.

data/docs/CONFIGURATION.md

@@ -0,0 +1,109 @@
+# Configuration Reference
+
+This document covers all configuration options for the DhanHQ Ruby client.
+
+## Quick Setup
+
+```ruby
+require 'dhan_hq'
+DhanHQ.configure_with_env
+```
+
+`configure_with_env` reads `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` from `ENV` and raises if either is missing.
+
+## Required Environment Variables
+
+| Variable             | Purpose                                           |
+| -------------------- | ------------------------------------------------- |
+| `DHAN_CLIENT_ID`     | Trading account client ID issued by Dhan          |
+| `DHAN_ACCESS_TOKEN`  | API access token generated from the Dhan console  |
+
+## Optional Environment Variables
+
+Set these _before_ calling `configure_with_env` to override defaults:
+
+| Variable                         | Default    | Description                                             |
+| -------------------------------- | ---------- | ------------------------------------------------------- |
+| `DHAN_LOG_LEVEL`                 | `INFO`     | Logger verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`)     |
+| `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname            |
+| `DHAN_WS_VERSION`                | latest     | Pin WebSocket connections to a specific API version     |
+| `DHAN_WS_ORDER_URL`              | Dhan prod  | Override the order update WebSocket endpoint            |
+| `DHAN_WS_USER_TYPE`              | `SELF`     | Switch between `SELF` and `PARTNER` streaming modes     |
+| `DHAN_PARTNER_ID`                | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_PARTNER_SECRET`            | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_CONNECT_TIMEOUT`           | `10`       | Connection timeout in seconds                           |
+| `DHAN_READ_TIMEOUT`              | `30`       | Read timeout in seconds                                 |
+| `DHAN_WRITE_TIMEOUT`             | `30`       | Write timeout in seconds                                |
+| `DHAN_WS_MAX_TRACKED_ORDERS`     | `10000`    | Maximum orders to track in WebSocket                    |
+| `DHAN_WS_MAX_ORDER_AGE`          | `604800`   | Maximum order age in seconds before cleanup (7 days)    |
+
+## `.env` File Setup
+
+Create a `.env` file in your project root:
+
+```dotenv
+DHAN_CLIENT_ID=your_client_id
+DHAN_ACCESS_TOKEN=your_access_token
+
+# Optional overrides
+DHAN_LOG_LEVEL=DEBUG
+DHAN_CONNECT_TIMEOUT=15
+DHAN_READ_TIMEOUT=60
+```
+
+The gem requires `dotenv/load`, so these variables are loaded automatically when you require `dhan_hq`.
+
+## Block-Style Configuration
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
+```
+
+## Logging
+
+```ruby
+DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+```
+
+Set `DHAN_LOG_LEVEL=DEBUG` for full HTTP request/response and WebSocket frame logging during development.
+
+## Dynamic Access Token
+
+For production or OAuth-style flows, resolve the token at **request time**:
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token_provider = lambda do
+    token = YourTokenStore.active_token  # e.g. from DB or OAuth
+    raise "Token expired or missing" unless token
+    token
+  end
+  # Optional: called when the API returns 401/token-expired
+  config.on_token_expired = ->(error) { YourTokenStore.refresh! }
+end
+```
+
+- **`access_token_provider`**: Callable (Proc/lambda) returning the token string. Called on every request (no memoization). When set, the gem uses it instead of `access_token`.
+- **`on_token_expired`**: Optional callable invoked when a 401/token-expired triggers a **single retry** (only when `access_token_provider` is set).
+
+For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
+
+## Available Resources
+
+| Resource                 | Model                                  | Actions                                             |
+| ------------------------ | -------------------------------------- | --------------------------------------------------- |
+| Orders                   | `DhanHQ::Models::Order`                | `find`, `all`, `where`, `place`, `update`, `cancel` |
+| Trades                   | `DhanHQ::Models::Trade`                | `all`, `find_by_order_id`                           |
+| Forever Orders           | `DhanHQ::Models::ForeverOrder`         | `create`, `find`, `modify`, `cancel`, `all`         |
+| Holdings                 | `DhanHQ::Models::Holding`              | `all`                                               |
+| Positions                | `DhanHQ::Models::Position`             | `all`, `find`, `exit!`                              |
+| Funds & Margin           | `DhanHQ::Models::Fund`                 | `fund_limit`, `margin_calculator`                   |
+| Ledger                   | `DhanHQ::Models::Ledger`               | `all`                                               |
+| Market Feeds             | `DhanHQ::Models::MarketFeed`           | `ltp`, `ohlc`, `quote`                              |
+| Historical Data (Charts) | `DhanHQ::Models::HistoricalData`       | `daily`, `intraday`                                 |
+| Option Chain             | `DhanHQ::Models::OptionChain`          | `fetch`, `fetch_expiry_list`                        |
+| Super Orders             | `DhanHQ::Models::SuperOrder`           | `create`, `modify`, `cancel`, `all`                 |

data/docs/SUPER_ORDERS.md

@@ -0,0 +1,284 @@
+# Super Orders — Full API Reference
+
+Super orders are built for smart execution. They club the entry, target, and stop-loss legs (with optional trailing jump) into a single request so you can manage risk immediately after entry.
+
+This gem exposes the full REST surface to create, modify, cancel, and list super orders across all supported exchanges and segments.
+
+## Endpoints
+
+| Method   | Path                                   | Description                           |
+| -------- | -------------------------------------- | ------------------------------------- |
+| `POST`   | `/super/orders`                        | Create a new super order              |
+| `PUT`    | `/super/orders/{order_id}`             | Modify a pending super order          |
+| `DELETE` | `/super/orders/{order_id}/{order_leg}` | Cancel a pending super order leg      |
+| `GET`    | `/super/orders`                        | Retrieve the list of all super orders |
+
+---
+
+## Place Super Order
+
+The place endpoint lets you submit a new super order that can include entry, target, stop-loss, and optional trailing jump definitions. It is available across exchanges and segments, and supports intraday, carry-forward, or MTF orders.
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking this API.
+
+```bash
+curl --request POST \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+### Request body
+
+```json
+{
+  "dhan_client_id": "1000000003",
+  "correlation_id": "123abc678",
+  "transaction_type": "BUY",
+  "exchange_segment": "NSE_EQ",
+  "product_type": "CNC",
+  "order_type": "LIMIT",
+  "security_id": "11536",
+  "quantity": 5,
+  "price": 1500,
+  "target_price": 1600,
+  "stop_loss_price": 1400,
+  "trailing_jump": 10
+}
+```
+
+### Parameters
+
+| Field              | Type                     | Description                                                                                                                                                                     |
+| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`   | string *(required)*      | User specific identification generated by Dhan. When you call through `DhanHQ::Models::SuperOrder`, the gem injects your configured client id so you can omit this key locally. |
+| `correlation_id`   | string                   | Caller generated correlation identifier                                                                                                                                         |
+| `transaction_type` | enum string *(required)* | Trading side. `BUY` or `SELL`.                                                                                                                                                  |
+| `exchange_segment` | enum string *(required)* | Exchange segment (see appendix).                                                                                                                                                |
+| `product_type`     | enum string *(required)* | Product type. `CNC`, `INTRADAY`, `MARGIN`, or `MTF`.                                                                                                                            |
+| `order_type`       | enum string *(required)* | Order type. `LIMIT` or `MARKET`.                                                                                                                                                |
+| `security_id`      | string *(required)*      | Exchange standard security identifier.                                                                                                                                          |
+| `quantity`         | integer *(required)*     | Number of shares for the order.                                                                                                                                                 |
+| `price`            | float *(required)*       | Price at which the entry leg is placed.                                                                                                                                         |
+| `target_price`     | float *(required)*       | Target price for the super order.                                                                                                                                               |
+| `stop_loss_price`  | float *(required)*       | Stop-loss price for the super order.                                                                                                                                            |
+| `trailing_jump`    | float *(required)*       | Price jump size used to trail the stop-loss.                                                                                                                                    |
+
+> 🐍 When you call `DhanHQ::Models::SuperOrder.create`, pass snake_case keys as shown above. The client automatically camelizes
+> them before posting to Dhan's REST API and injects your configured `dhan_client_id`, so you can omit that key in Ruby code.
+
+### Response
+
+```json
+{
+  "order_id": "112111182198",
+  "order_status": "PENDING"
+}
+```
+
+| Field          | Type        | Description                                         |
+| -------------- | ----------- | --------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                  |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, or `REJECTED`. |
+
+---
+
+## Modify Super Order
+
+Use the modify endpoint to update any leg while the super order remains in `PENDING` or `PART_TRADED` status.
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking this API.
+
+```bash
+curl --request PUT \
+  --url https://api.dhan.co/v2/super/orders/{order_id} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+### Request body
+
+```json
+{
+  "dhan_client_id": "1000000009",
+  "order_id": "112111182045",
+  "order_type": "LIMIT",
+  "leg_name": "ENTRY_LEG",
+  "quantity": 40,
+  "price": 1300,
+  "target_price": 1450,
+  "stop_loss_price": 1350,
+  "trailing_jump": 20
+}
+```
+
+### Parameters
+
+| Field             | Type                                   | Description                                                                                                               |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`  | string *(required)*                    | User specific identification generated by Dhan. Automatically added when you call through the Ruby models.                |
+| `order_id`        | string *(required)*                    | Super order identifier generated by Dhan.                                                                                 |
+| `order_type`      | enum string *(conditionally required)* | `LIMIT` or `MARKET`. Required when modifying `ENTRY_LEG`.                                                                 |
+| `leg_name`        | enum string *(required)*               | `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`. Entry leg updates entire order while status is `PENDING` or `PART_TRADED`. |
+| `quantity`        | integer *(conditionally required)*     | Quantity update for `ENTRY_LEG`.                                                                                          |
+| `price`           | float *(conditionally required)*       | Entry price update for `ENTRY_LEG`.                                                                                       |
+| `target_price`    | float *(conditionally required)*       | Target price update for `ENTRY_LEG` or `TARGET_LEG`.                                                                      |
+| `stop_loss_price` | float *(conditionally required)*       | Stop-loss price update for `ENTRY_LEG` or `STOP_LOSS_LEG`.                                                                |
+| `trailing_jump`   | float *(conditionally required)*       | Trailing jump update for `ENTRY_LEG` or `STOP_LOSS_LEG`. Omit or set to `0` to cancel trailing.                           |
+
+> ℹ️ Once the entry leg status becomes `TRADED`, only the `TARGET_LEG` and `STOP_LOSS_LEG` can be modified (price and trailing jump).
+
+### Response
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "TRANSIT"
+}
+```
+
+| Field          | Type        | Description                                                   |
+| -------------- | ----------- | ------------------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                            |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, `REJECTED`, or `TRADED`. |
+
+---
+
+## Cancel Super Order
+
+Cancel a pending or active super order leg using the order ID. Cancelling the entry leg removes every leg. Cancelling a specific target or stop-loss leg removes only that leg and it cannot be re-added.
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking this API.
+
+```bash
+curl --request DELETE \
+  --url https://api.dhan.co/v2/super/orders/{order_id}/{order_leg} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+### Path parameters
+
+| Field       | Description                                                   | Example       |
+| ----------- | ------------------------------------------------------------- | ------------- |
+| `order_id`  | Super order identifier.                                       | `11211182198` |
+| `order_leg` | Leg to cancel. `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`. | `ENTRY_LEG`   |
+
+### Response
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "CANCELLED"
+}
+```
+
+| Field          | Type        | Description                                                      |
+| -------------- | ----------- | ---------------------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                               |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, `REJECTED`, or `CANCELLED`. |
+
+---
+
+## Super Order List
+
+List every super order placed during the trading day. The API nests leg details under the entry leg, and individual legs also appear in the main order book.
+
+```bash
+curl --request GET \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+### Response
+
+```json
+[
+  {
+    "dhan_client_id": "1100003626",
+    "order_id": "5925022734212",
+    "correlation_id": "string",
+    "order_status": "PENDING",
+    "transaction_type": "BUY",
+    "exchange_segment": "NSE_EQ",
+    "product_type": "CNC",
+    "order_type": "LIMIT",
+    "validity": "DAY",
+    "trading_symbol": "HDFCBANK",
+    "security_id": "1333",
+    "quantity": 10,
+    "remaining_quantity": 10,
+    "ltp": 1660.95,
+    "price": 1500,
+    "after_market_order": false,
+    "leg_name": "ENTRY_LEG",
+    "exchange_order_id": "11925022734212",
+    "create_time": "2025-02-27 19:09:42",
+    "update_time": "2025-02-27 19:09:42",
+    "exchange_time": "2025-02-27 19:09:42",
+    "oms_error_description": "",
+    "average_traded_price": 0,
+    "filled_qty": 0,
+    "leg_details": [
+      {
+        "order_id": "5925022734212",
+        "leg_name": "STOP_LOSS_LEG",
+        "transaction_type": "SELL",
+        "total_quantity": 0,
+        "remaining_quantity": 0,
+        "triggered_quantity": 0,
+        "price": 1400,
+        "order_status": "PENDING",
+        "trailing_jump": 10
+      },
+      {
+        "order_id": "5925022734212",
+        "leg_name": "TARGET_LEG",
+        "transaction_type": "SELL",
+        "remaining_quantity": 0,
+        "triggered_quantity": 0,
+        "price": 1550,
+        "order_status": "PENDING",
+        "trailing_jump": 0
+      }
+    ]
+  }
+]
+```
+
+### Response Parameters
+
+| Field                   | Type        | Description                                                                                         |
+| ----------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`        | string      | User specific identification generated by Dhan.                                                     |
+| `order_id`              | string      | Order identifier generated by Dhan.                                                                 |
+| `correlation_id`        | string      | Correlation identifier supplied by the caller.                                                      |
+| `order_status`          | enum string | Latest status. `TRANSIT`, `PENDING`, `CLOSED`, `REJECTED`, `CANCELLED`, `PART_TRADED`, or `TRADED`. |
+| `transaction_type`      | enum string | Trading side. `BUY` or `SELL`.                                                                      |
+| `exchange_segment`      | enum string | Exchange segment.                                                                                   |
+| `product_type`          | enum string | Product type. `CNC`, `INTRADAY`, `MARGIN`, or `MTF`.                                                |
+| `order_type`            | enum string | Order type. `LIMIT` or `MARKET`.                                                                    |
+| `validity`              | enum string | Order validity. `DAY`.                                                                              |
+| `trading_symbol`        | string      | Trading symbol reference.                                                                           |
+| `security_id`           | string      | Exchange security identifier.                                                                       |
+| `quantity`              | integer     | Ordered quantity.                                                                                   |
+| `remaining_quantity`    | integer     | Quantity pending execution.                                                                         |
+| `ltp`                   | float       | Last traded price.                                                                                  |
+| `price`                 | float       | Order price.                                                                                        |
+| `after_market_order`    | boolean     | Indicates if the order was placed after market hours.                                               |
+| `leg_name`              | enum string | Leg identifier: `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`.                                      |
+| `trailing_jump`         | float       | Trailing jump for stop-loss.                                                                        |
+| `exchange_order_id`     | string      | Exchange-generated order identifier.                                                                |
+| `create_time`           | string      | Order creation timestamp.                                                                           |
+| `update_time`           | string      | Latest update timestamp.                                                                            |
+| `exchange_time`         | string      | Exchange timestamp.                                                                                 |
+| `oms_error_description` | string      | OMS error description when applicable.                                                              |
+| `average_traded_price`  | float       | Average traded price.                                                                               |
+| `filled_qty`            | integer     | Quantity traded on the exchange.                                                                    |
+| `triggered_quantity`    | integer     | Quantity triggered for stop-loss or target legs.                                                    |
+| `leg_details`           | array       | Nested leg details for the super order.                                                             |
+
+> ✅ `CLOSED` indicates the entry leg plus either target or stop-loss leg completed for the entire quantity. `TRIGGERED` appears on target and stop-loss legs to show which leg fired; inspect `triggered_quantity` for the executed quantity.

data/docs/TESTING_GUIDE.md

@@ -72,8 +72,8 @@ puts "Token provider: #{DhanHQ.configuration.access_token_provider ? 'Set' : 'No
 
 ```ruby
 # Check current environment variables
-puts "CLIENT_ID: #{ENV['CLIENT_ID']}"
-puts "ACCESS_TOKEN: #{ENV['ACCESS_TOKEN'] ? 'Set' : 'Not Set'}"
+puts "DHAN_CLIENT_ID: #{ENV['DHAN_CLIENT_ID']}"
+puts "DHAN_ACCESS_TOKEN: #{ENV['DHAN_ACCESS_TOKEN'] ? 'Set' : 'Not Set'}"
 puts "DHAN_LOG_LEVEL: #{ENV['DHAN_LOG_LEVEL'] || 'INFO'}"
 puts "DHAN_CONNECT_TIMEOUT: #{ENV['DHAN_CONNECT_TIMEOUT'] || '10'}"
 puts "DHAN_READ_TIMEOUT: #{ENV['DHAN_READ_TIMEOUT'] || '30'}"
@@ -521,7 +521,7 @@ if position
     to_product_type: "MARGIN",
     quantity: position.net_qty.abs
   )
-  
+
   if result
     puts "Position converted successfully"
   else
@@ -784,22 +784,22 @@ if instrument
   # Get LTP
   ltp_data = instrument.ltp
   puts "LTP: ₹#{ltp_data[:last_price]}"
-  
+
   # Get OHLC
   ohlc_data = instrument.ohlc
   puts "OHLC: #{ohlc_data[:ohlc]}"
-  
+
   # Get Quote
   quote_data = instrument.quote
   puts "Quote: #{quote_data[:ltp]}"
-  
+
   # Get Daily Historical Data
   daily_data = instrument.daily(
     from_date: Date.today - 7,
     to_date: Date.today
   )
   puts "Daily candles: #{daily_data.size}"
-  
+
   # Get Intraday Historical Data
   intraday_data = instrument.intraday(
     from_date: Date.today,
@@ -807,7 +807,7 @@ if instrument
     interval: 5
   )
   puts "Intraday candles: #{intraday_data.size}"
-  
+
   # Get Expiry List (for F&O instruments)
   if instrument.instrument == "FUTSTK" || instrument.instrument == "OPTSTK"
     expiry_list = instrument.expiry_list