DhanHQ 2.1.5 → 2.1.6

data/README1.md

@@ -423,40 +423,281 @@ end
 
 ---
 
-## Super Orders (example)
+## Super Orders
 
-```ruby
-intent = {
-  exchange_segment: "NSE_FNO",
-  security_id:      "12345",   # option
-  transaction_type: "BUY",
-  quantity:         50,
-  # derived risk params from ATR/ADX
-  take_profit:      0.35,      # 35% target
-  stop_loss:        0.18,      # 18% SL
-  trailing_sl:      0.12       # 12% trail
+Super orders are built for smart execution. They bundle entry, target, and stop-loss legs (with optional trailing jump) into one atomic request so the broker manages risk for you.
+
+The gem exposes all related REST endpoints so you can create, modify, cancel, and list super orders programmatically across 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
+
+Use this endpoint to create a new super order consisting of entry, target, stop-loss, and optional trailing jump. It is available for intraday, carry-forward, and MTF across supported exchanges.
+
+> ℹ️ 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
 }
+```
 
-# If your SuperOrder model exposes create/modify:
-o = DhanHQ::Models::SuperOrder.create(intent)
-# or fallback:
-mkt = DhanHQ::Models::Order.new(
-  transaction_type: "BUY", exchange_segment: "NSE_FNO",
-  order_type: "MARKET", validity: "DAY",
-  security_id: "12345", quantity: 50
-).save
+#### Parameters
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `dhan_client_id` | string *(required)* | User specific identification generated by Dhan. When you call via `DhanHQ::Models::SuperOrder`, the gem injects your configured client id so you can omit the key in Ruby. |
+| `correlation_id` | string | Caller supplied identifier for tracking |
+| `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)* | Quantity for the entry leg. |
+| `price` | float *(required)* | Entry price. |
+| `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 for trailing stop-loss. |
+
+> 🐍 When you call `DhanHQ::Models::SuperOrder.create`, supply snake_case keys exactly as shown. The client automatically camelizes
+> them before submitting to Dhan's REST API and injects your configured `dhan_client_id`, allowing you to omit the key in Ruby code.
+
+#### Response
+
+```json
+{
+  "order_id": "112111182198",
+  "order_status": "PENDING"
+}
 ```
 
-If you placed a Super Order and want to trail SL upward using WS ticks:
+| Field | Type | Description |
+| --- | --- | --- |
+| `order_id` | string | Order identifier generated by Dhan |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, or `REJECTED`. |
 
-```ruby
-DhanHQ::Models::SuperOrder.modify(
-  order_id: o.order_id,
-  stop_loss: new_abs_price,    # broker API permitting
-  trailing_sl: nil
-)
+### Modify Super Order
+
+Modify any leg while the order is `PENDING` or `PART_TRADED`. Once the entry leg trades fully, only the target and stop-loss legs (price and trailing jump) remain editable.
+
+> ℹ️ 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 merged when using the Ruby model helpers. |
+| `order_id` | string *(required)* | Super order identifier generated by Dhan. |
+| `order_type` | enum string *(conditionally required)* | `LIMIT` or `MARKET`. Required when changing `ENTRY_LEG`. |
+| `leg_name` | enum string *(required)* | `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`. Entry edits allowed only 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. |
+
+#### 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 with the order ID. Cancelling the entry leg removes all legs. Cancelling an individual target or stop-loss leg removes only that leg and it cannot be recreated on the same order.
+
+> ℹ️ 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
+
+Fetch all super orders placed during the trading day. The response nests leg details under the entry leg, and each leg is also available in the standard 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
+      }
+    ]
+  }
+]
+```
+
+#### 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 | Caller supplied correlation identifier. |
+| `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 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 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 and either target or stop-loss completed for the full quantity. `TRIGGERED` appears on target and stop-loss legs to highlight which one fired; inspect `triggered_quantity` for executed quantity.
+
 ---
 
 ## Packet parsing (for reference)

data/docs/live_order_updates.md

@@ -0,0 +1,319 @@
+# Live Order Updates - Comprehensive Guide
+
+The DhanHQ Ruby client provides comprehensive real-time order update functionality via WebSocket, covering all order states as per the [DhanHQ API documentation](https://dhanhq.co/docs/v2).
+
+## Features
+
+✅ **Complete Order State Tracking** - All order statuses (TRANSIT, PENDING, REJECTED, CANCELLED, TRADED, EXPIRED)
+✅ **Real-time Execution Updates** - Track partial and full executions
+✅ **Order State Management** - Query orders by status, symbol, execution state
+✅ **Event-driven Architecture** - Subscribe to specific order events
+✅ **Super Order Support** - Track entry, stop-loss, and target legs
+✅ **Comprehensive Order Data** - All fields from API documentation
+
+## Quick Start
+
+### Basic Usage
+
+```ruby
+require 'dhan_hq'
+
+# Configure credentials
+DhanHQ.configure do |config|
+  config.client_id = "your_client_id"
+  config.access_token = "your_access_token"
+end
+
+# Simple order update monitoring
+DhanHQ::WS::Orders.connect do |order_update|
+  puts "Order Update: #{order_update.symbol} - #{order_update.status}"
+  puts "Quantity: #{order_update.traded_qty}/#{order_update.quantity}"
+end
+```
+
+### Advanced Usage with Event Handlers
+
+```ruby
+# Create client with multiple event handlers
+client = DhanHQ::WS::Orders.connect_with_handlers({
+  :update => ->(order) { puts "Order updated: #{order.order_no}" },
+  :status_change => ->(data) {
+    puts "Status changed: #{data[:previous_status]} -> #{data[:new_status]}"
+  },
+  :execution => ->(data) {
+    puts "Execution: #{data[:new_traded_qty]} shares at #{data[:order_update].avg_traded_price}"
+  },
+  :order_traded => ->(order) { puts "Order fully executed: #{order.order_no}" },
+  :order_rejected => ->(order) { puts "Order rejected: #{order.reason_description}" }
+})
+
+# Keep the connection alive
+sleep
+```
+
+## Order Update Model
+
+The `OrderUpdate` model provides comprehensive access to all order fields:
+
+### Order Information
+```ruby
+order_update.order_no          # Order number
+order_update.exch_order_no     # Exchange order number
+order_update.symbol            # Trading symbol
+order_update.display_name      # Instrument display name
+order_update.security_id       # Security ID
+order_update.correlation_id    # User correlation ID
+```
+
+### Order Details
+```ruby
+order_update.txn_type          # "B" for Buy, "S" for Sell
+order_update.order_type        # "LMT", "MKT", "SL", "SLM"
+order_update.product           # "C", "I", "M", "F", "V", "B"
+order_update.validity          # "DAY", "IOC"
+order_update.status            # "TRANSIT", "PENDING", "REJECTED", etc.
+```
+
+### Execution Information
+```ruby
+order_update.quantity          # Total order quantity
+order_update.traded_qty         # Executed quantity
+order_update.remaining_quantity # Pending quantity
+order_update.price              # Order price
+order_update.traded_price       # Last trade price
+order_update.avg_traded_price   # Average execution price
+```
+
+### Helper Methods
+
+#### Transaction Type
+```ruby
+order_update.buy?              # true if BUY order
+order_update.sell?             # true if SELL order
+```
+
+#### Order Type
+```ruby
+order_update.limit_order?      # true if LIMIT order
+order_update.market_order?     # true if MARKET order
+order_update.stop_loss_order?  # true if STOP LOSS order
+```
+
+#### Product Type
+```ruby
+order_update.cnc_product?      # true if CNC
+order_update.intraday_product? # true if INTRADAY
+order_update.margin_product?   # true if MARGIN
+order_update.mtf_product?      # true if MTF
+order_update.cover_order?      # true if CO
+order_update.bracket_order?    # true if BO
+```
+
+#### Order Status
+```ruby
+order_update.transit?          # true if TRANSIT
+order_update.pending?           # true if PENDING
+order_update.rejected?          # true if REJECTED
+order_update.cancelled?         # true if CANCELLED
+order_update.traded?            # true if TRADED
+order_update.expired?           # true if EXPIRED
+```
+
+#### Execution State
+```ruby
+order_update.partially_executed? # true if partially filled
+order_update.fully_executed?     # true if fully filled
+order_update.not_executed?       # true if not filled
+order_update.execution_percentage # execution percentage (0-100)
+```
+
+#### Super Order Legs
+```ruby
+order_update.entry_leg?         # true if entry leg (leg_no == 1)
+order_update.stop_loss_leg?     # true if stop-loss leg (leg_no == 2)
+order_update.target_leg?        # true if target leg (leg_no == 3)
+order_update.super_order?        # true if part of super order
+```
+
+## Client Methods
+
+### Order Tracking
+```ruby
+client = DhanHQ::WS::Orders.client.start
+
+# Get specific order state
+order = client.order_state("1124091136546")
+
+# Get all tracked orders
+all_orders = client.all_orders
+
+# Query orders by status
+pending_orders = client.orders_by_status("PENDING")
+traded_orders = client.orders_by_status("TRADED")
+
+# Query orders by symbol
+reliance_orders = client.orders_by_symbol("RELIANCE")
+
+# Query by execution state
+partial_orders = client.partially_executed_orders
+full_orders = client.fully_executed_orders
+pending_orders = client.pending_orders
+```
+
+### Event Handling
+```ruby
+client = DhanHQ::WS::Orders.client
+
+# General events
+client.on(:update) { |order| puts "Order updated: #{order.order_no}" }
+client.on(:raw) { |msg| puts "Raw message: #{msg}" }
+client.on(:close) { puts "Connection closed" }
+
+# Status-specific events
+client.on(:order_transit) { |order| puts "Order in transit: #{order.order_no}" }
+client.on(:order_pending) { |order| puts "Order pending: #{order.order_no}" }
+client.on(:order_rejected) { |order| puts "Order rejected: #{order.reason_description}" }
+client.on(:order_cancelled) { |order| puts "Order cancelled: #{order.order_no}" }
+client.on(:order_traded) { |order| puts "Order traded: #{order.order_no}" }
+client.on(:order_expired) { |order| puts "Order expired: #{order.order_no}" }
+
+# State change events
+client.on(:status_change) do |data|
+  puts "Status: #{data[:previous_status]} -> #{data[:new_status]}"
+end
+
+client.on(:execution) do |data|
+  puts "Execution: #{data[:new_traded_qty]} shares (#{data[:execution_percentage]}%)"
+end
+
+client.start
+```
+
+## Configuration
+
+### Environment Variables
+```bash
+# Required
+CLIENT_ID=your_client_id
+ACCESS_TOKEN=your_access_token
+
+# Optional WebSocket settings
+DHAN_WS_ORDER_URL=wss://api-order-update.dhan.co
+DHAN_WS_USER_TYPE=SELF  # or PARTNER
+DHAN_PARTNER_ID=partner_id      # if UserType is PARTNER
+DHAN_PARTNER_SECRET=partner_secret  # if UserType is PARTNER
+```
+
+### Programmatic Configuration
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = "your_client_id"
+  config.access_token = "your_access_token"
+  config.ws_order_url = "wss://api-order-update.dhan.co"
+  config.ws_user_type = "SELF"  # or "PARTNER"
+
+  # For partner mode
+  config.partner_id = "partner_id"
+  config.partner_secret = "partner_secret"
+end
+```
+
+## Complete Example
+
+```ruby
+require 'dhan_hq'
+
+# Configure
+DhanHQ.configure_with_env
+
+# Create order tracking client
+client = DhanHQ::WS::Orders.client
+
+# Set up comprehensive event handling
+client.on(:update) do |order|
+  puts "\n=== Order Update ==="
+  puts "Order: #{order.order_no} | Symbol: #{order.symbol}"
+  puts "Status: #{order.status} | Type: #{order.txn_type}"
+  puts "Quantity: #{order.traded_qty}/#{order.quantity} (#{order.execution_percentage}%)"
+  puts "Price: #{order.price} | Avg Price: #{order.avg_traded_price}"
+  puts "Leg: #{order.leg_no} | Super Order: #{order.super_order?}"
+end
+
+client.on(:status_change) do |data|
+  order = data[:order_update]
+  puts "\n🔄 Status Change: #{order.order_no}"
+  puts "   #{data[:previous_status]} -> #{data[:new_status]}"
+end
+
+client.on(:execution) do |data|
+  order = data[:order_update]
+  puts "\n💰 Execution Update: #{order.order_no}"
+  puts "   #{data[:previous_traded_qty]} -> #{data[:new_traded_qty]} shares"
+  puts "   Execution: #{data[:execution_percentage]}%"
+end
+
+client.on(:order_traded) do |order|
+  puts "\n✅ Order Fully Executed: #{order.order_no}"
+  puts "   Symbol: #{order.symbol} | Quantity: #{order.traded_qty}"
+  puts "   Average Price: #{order.avg_traded_price}"
+end
+
+client.on(:order_rejected) do |order|
+  puts "\n❌ Order Rejected: #{order.order_no}"
+  puts "   Reason: #{order.reason_description}"
+end
+
+# Start monitoring
+puts "Starting order update monitoring..."
+client.start
+
+# Keep running
+begin
+  loop do
+    sleep 1
+
+    # Print order summary every 30 seconds
+    if Time.now.to_i % 30 == 0
+      puts "\n📊 Order Summary:"
+      puts "   Total Orders: #{client.all_orders.size}"
+      puts "   Pending: #{client.orders_by_status('PENDING').size}"
+      puts "   Traded: #{client.orders_by_status('TRADED').size}"
+      puts "   Rejected: #{client.orders_by_status('REJECTED').size}"
+    end
+  end
+rescue Interrupt
+  puts "\nShutting down..."
+  client.stop
+end
+```
+
+## Order States Covered
+
+The implementation covers all order states as per DhanHQ API documentation:
+
+| Status      | Description                  | Event              |
+| ----------- | ---------------------------- | ------------------ |
+| `TRANSIT`   | Order in transit to exchange | `:order_transit`   |
+| `PENDING`   | Order pending at exchange    | `:order_pending`   |
+| `REJECTED`  | Order rejected by exchange   | `:order_rejected`  |
+| `CANCELLED` | Order cancelled              | `:order_cancelled` |
+| `TRADED`    | Order fully executed         | `:order_traded`    |
+| `EXPIRED`   | Order expired                | `:order_expired`   |
+
+## Error Handling
+
+The WebSocket client includes comprehensive error handling:
+
+- **Automatic Reconnection** with exponential backoff
+- **Rate Limit Handling** with 60-second cool-off for 429 errors
+- **Connection Monitoring** with health checks
+- **Event Handler Protection** - errors in handlers don't crash the client
+
+## Thread Safety
+
+All operations are thread-safe using `Concurrent::Map` and `Concurrent::AtomicBoolean` for:
+- Order state tracking
+- Event callback management
+- Connection state management
+
+This ensures safe usage in multi-threaded applications.