DhanHQ 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b583e87aa598f3891e937f44859f9b451fc8f6bcec7a304cc0c33790fe9117ea
-  data.tar.gz: 1a090fa608fba141da311ba8aaf21d36e750f78e90497f728c5f96d580044c7e
+  metadata.gz: 30825da308f5f85870f4efe9b702f7e2f653840b396b3265d36383d4a8c56f5e
+  data.tar.gz: b2874edeb45b60b6e68b4d8c69b9e9e3c6a0b6d2734ca645168626afd27cde76
 SHA512:
-  metadata.gz: '0966f2a2aa331b675ecc1675510f6ad3dca6b7a987c8dde15dde2efe506ac659157b6e0979d0c23f480d2835fa603bfd37530f33275d422226abb2419e46bfd0'
-  data.tar.gz: 74ea10d0744fb01324afd4a1768fa6969b07f4d1fcb9da94d7a6caf01fd01c2863d6a3746d288628d10e497bd55c68687e0b54e237bd91736ad4bb8c1decc9f8
+  metadata.gz: fe803337db74aa9689001b458627a532101fd0d298142b74ed0fefd87e7938ef4fd2b5e75bb53d871d8c535df35347065a43428986d930e6a0fa1ebae0c19aaf
+  data.tar.gz: aae78dbbbea337312262239f083c8fbb96f65b51b2d70cb9dce2683204f5e506d5a0835c85af6766ce0233262e79aaaf5dde45561eb410d51c52c74a185d5184

data/.rubocop.yml

@@ -6,6 +6,7 @@ plugins:
 
 require:
   - rubocop-rake
+  - ./lib/rubocop/cop/dhanhq/use_constants.rb
 
 AllCops:
   TargetRubyVersion: 3.2
@@ -25,4 +26,11 @@ RSpec/ExampleLength:
   Max: 15
 
 RSpec/MultipleMemoizedHelpers:
-  Max: 10
+  Max: 10
+
+DhanHQ/UseConstants:
+  Enabled: true
+  Exclude:
+    - 'lib/DhanHQ/constants.rb'
+    - 'lib/DhanHQ/ws/segments.rb'
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -1,4 +1,100 @@
-## [Unreleased]
+## [2.6.0] - 2026-03-06
+
+### Fixed (API docs alignment)
+
+- **Kill Switch**: Manage API now uses query parameter per [dhanhq.co/docs/v2/traders-control](https://dhanhq.co/docs/v2/traders-control/). `Resources::KillSwitch#update(status)` sends `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or `DEACTIVATE`) with no body. `Models::KillSwitch.update("ACTIVATE")` / `.activate` / `.deactivate` unchanged.
+- **IP Setup**: Set/Modify now send required API fields. `Resources::IPSetup#set` and `#update` accept `ip:`, `ip_flag: "PRIMARY"` (or `"SECONDARY"`), and optional `dhan_client_id:` (defaults from `DhanHQ.configuration.client_id`). See [dhanhq.co/docs/v2/authentication/#setup-static-ip](https://dhanhq.co/docs/v2/authentication/#setup-static-ip).
+- **Alert Orders (Conditional Trigger)**: Condition now requires `exchange_segment`, `exp_date`, and `frequency` per [dhanhq.co/docs/v2/conditional-trigger](https://dhanhq.co/docs/v2/conditional-trigger/). `time_frame` is required when `comparison_type` starts with `TECHNICAL`. `AlertOrderContract` and all examples updated.
+
+### Breaking changes
+
+- **AlertOrder.create / AlertOrderContract**: Contract expects nested structure (see 2.5.0). Condition hash must include `exchange_segment`, `exp_date`, and `frequency`; for `comparison_type` starting with `TECHNICAL`, `time_frame` is required. See GUIDE.md and [conditional-trigger](https://dhanhq.co/docs/v2/conditional-trigger/).
+- **Resources::KillSwitch#update**: Signature is now `update(status)` (string). Use `update("ACTIVATE")` or `Models::KillSwitch.activate` / `.deactivate`, unchanged.
+- **AlertOrderContract** — expected payload shape:
+
+```ruby
+AlertOrderContract.new.call(
+  condition: {
+    exchange_segment:  "NSE_EQ",
+    security_id:       "11536",
+    comparison_type:   "PRICE_WITH_VALUE",
+    operator:          "GREATER_THAN",
+    exp_date:          "2026-12-31",
+    frequency:         "ONCE"
+  },
+  orders: [
+    { transaction_type: "BUY", exchange_segment: "NSE_EQ", product_type: "INTRADAY", order_type: "MARKET", security_id: "11536", quantity: 5, validity: "DAY" }
+  ]
+)
+```
+
+### Added
+
+#### Order Model — New Public Methods
+- **`Order#destroy` / `#delete`**: Cancels an order via `DELETE /v2/orders/{id}`. Returns `true` if the API confirms `CANCELLED` status, `false` otherwise. `#delete` is an alias.
+- **`Order#slice_order(params)`**: Splits a large order into multiple legs to exceed freeze-limit quantities on F&O instruments via `POST /v2/slicing`. Delegates to `Resources::Orders#slicing`.
+- **`Order#save`**: ActiveRecord-style save — places a new order for new records, modifies existing records. Returns `true`/`false`.
+- **`Order.place` — `dhan_client_id` auto-injection**: If `dhan_client_id` is not passed in params, it is automatically read from `DhanHQ.configuration.client_id`. Existing code that passes `dhan_client_id` explicitly continues to work unchanged.
+
+#### Contract Hardening
+- **`OrderContract`** (base for `PlaceOrderContract` and `ModifyOrderContract`) now enforces:
+  - `LIMIT` orders require `price`; `MARKET` orders reject `price`
+  - `STOP_LOSS` / `STOP_LOSS_MARKET` require `trigger_price`
+  - Stop-loss price relationships: BUY requires `trigger_price >= price`; SELL requires `trigger_price <= price`
+  - Bracket Order (BO): both `bo_profit_value` and `bo_stop_loss_value` required; directional profit/loss relationship validated
+  - `disclosed_quantity` cannot exceed 30% of `quantity`
+  - `amo_time` required when `after_market_order: true`
+  - Lot-size and tick-size enforcement when `instrument_meta` is provided
+  - Segment-based product restrictions (CNC equity-only, BO/CO currency restrictions)
+- **`ModifyOrderContract`**: Requires at least one modifiable field; inherits all `OrderContract` business rules.
+- **New contracts**: `EdisContract`, `UserIpContract`, `PnlBasedExitContract`, `MultiScripMarginCalcContract`, `SliceOrderContract`.
+
+#### Infrastructure
+- **`ApiResponseHandler` concern** (`lib/DhanHQ/models/concerns/api_response_handler.rb`): Shared module for uniform API response handling, attribute merging, and structured logging. Included in `Order` and `ForeverOrder`.
+- **Global Constants Enforcement**: Replaced all hardcoded API strings with `DhanHQ::Constants` across the repository. Built a custom RuboCop cop (`RuboCop::Cop::DhanHQ::UseConstants`) that strictly enforces typed constants instead of loose strings for robust API payloads.
+- **Constants Documentation**: Added `docs/CONSTANTS_REFERENCE.md` detailing all SDK constants (e.g., `ExchangeSegment`, `ProductType`, `OrderType`, etc.).
+
+### Changed
+- Replaced 160+ hardcoded usages of strings like `"NSE_EQ"` and `"BUY"` with `DhanHQ::Constants::ExchangeSegment::NSE_EQ` and `DhanHQ::Constants::TransactionType::BUY`.
+- Added `NO_HOLDINGS` (value `"DH-1111"`) to `TradingErrorCode`.
+- `PlaceOrderContract` refactored to inherit from `OrderContract`, eliminating duplicated validation logic. Derivative-specific fields (`drv_expiry_date`, `drv_option_type`, `drv_strike_price`) remain on `PlaceOrderContract`.
+- `Resources::Orders` now fetches optional instrument metadata (lot size, tick size) to pass into contract validation.
+
+---
+
+## [2.5.0] - 2026-02-21
+
+### Added
+
+#### New Endpoints — Full Dhan API v2 Parity
+- **Exit All Positions**: `DhanHQ::Models::Position.exit_all!` — emergency closure of all positions and cancellation of all open orders via `DELETE /v2/positions`. Resource method: `DhanHQ::Resources::Positions#exit_all`.
+- **Kill Switch Status**: `DhanHQ::Models::KillSwitch.status` — query current kill switch state via `GET /v2/killswitch`. Resource method: `DhanHQ::Resources::KillSwitch#status`.
+- **P&L Based Exit**: New `DhanHQ::Models::PnlExit` model and `DhanHQ::Resources::PnlExit` resource for automatic profit/loss-based position exit:
+  - `PnlExit.configure(profit_value:, loss_value:, product_type:, enable_kill_switch:)` — `POST /v2/pnlExit`
+  - `PnlExit.stop` — `DELETE /v2/pnlExit`
+  - `PnlExit.status` — `GET /v2/pnlExit`
+- **Multi-Order Margin Calculator**: `DhanHQ::Models::Margin.calculate_multi` — batch margin calculation with hedge benefit across multiple instruments via `POST /v2/margincalculator/multi`. Resource method: `DhanHQ::Resources::MarginCalculator#calculate_multi`.
+- **EDIS Model**: New `DhanHQ::Models::Edis` wrapping existing `DhanHQ::Resources::Edis` with ORM-style class methods:
+  - `Edis.generate_tpin`, `Edis.generate_form`, `Edis.generate_bulk_form`, `Edis.inquire`
+- **Postback Payload Parser**: New `DhanHQ::Models::Postback` utility model for parsing Dhan webhook payloads:
+  - `Postback.parse(json_or_hash)` — accepts JSON string or Hash
+  - Status predicates: `traded?`, `rejected?`, `pending?`, `cancelled?`
+- **AlertOrder Modify**: Explicit `DhanHQ::Models::AlertOrder.modify(alert_id, params)` class method for updating conditional triggers with better discoverability.
+
+#### Tests
+- **28 new specs** across 7 files (442 total, 0 failures):
+  - `spec/dhan_hq/models/pnl_exit_spec.rb` — configure, stop, status, defaults, nil handling
+  - `spec/dhan_hq/models/edis_spec.rb` — generate_tpin, generate_form, bulk_form, inquire
+  - `spec/dhan_hq/models/postback_spec.rb` — JSON/Hash parsing, snake_case support, status predicates
+  - Updated: `kill_switch_spec.rb`, `positions_spec.rb`, `margin_spec.rb`, `alert_order_spec.rb`
+
+### Changed
+- **README.md**: Updated Key Features to reflect full API v2 parity including P&L Exit, Postback parser, and EDIS model.
+- **Bundler**: Updated `BUNDLED WITH` to latest version, eliminating platform constant re-definition warnings.
+
+### Notes
+- **Backward Compatible**: All changes are additive — no existing APIs or method signatures changed.
+- **Full API v2 Parity**: The gem now covers every endpoint documented at [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/).
 
 ---
 
@@ -23,7 +119,7 @@
 
 ### Added
 - **Alert Orders**: `DhanHQ::Resources::AlertOrders` (BaseResource) and `DhanHQ::Models::AlertOrder` with full CRUD. Endpoints: GET/POST `/alerts/orders`, GET/PUT/DELETE `/alerts/orders/{id}` (per API docs). Validation via `DhanHQ::Contracts::AlertOrderContract`.
-- **IP Setup**: `DhanHQ::Resources::IPSetup` (resource-only). Methods: `current` (GET `/ip/getIP`), `set(ip:)` (POST `/ip/setIP`), `update(ip:)` (PUT `/ip/modifyIP`) per API docs.
+- **IP Setup**: `DhanHQ::Resources::IPSetup` (resource-only). Methods: `current` (GET `/ip/getIP`), `set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` (POST `/ip/setIP`), `update(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` (PUT `/ip/modifyIP`). Body includes `dhanClientId` (default from config) and `ipFlag` per API docs.
 - **Trader Control (Kill Switch)**: `DhanHQ::Resources::TraderControl` (resource-only). Methods: `status` (GET `/trader-control`), `enable` (POST action ENABLE), `disable` (POST action DISABLE). `DhanHQ::Resources::KillSwitch` and `DhanHQ::Models::KillSwitch` remain for backward compatibility.
 - **docs/API_VERIFICATION.md**: Documents alignment with [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/) and [api.dhan.co/v2](https://api.dhan.co/v2/#/) for EDIS, Alert Orders, IP Setup.
 
@@ -60,9 +156,9 @@
 - **README.md**: Note under Dynamic access token for RenewToken via `DhanHQ::Auth.renew_token` and that API key/Partner flows are implemented in the app.
 - **GUIDE.md**: “Dynamic access token” section extended with RenewToken (`DhanHQ::Auth.renew_token`) and note that API key/Partner flows are in the app.
 - **docs/TESTING_GUIDE.md**: Optional config comment for RenewToken and pointer to AUTHENTICATION.md (API key/Partner in app).
-- **docs/rails_integration.md**: “Dynamic access token” section extended with RenewToken (web-generated tokens) and link to AUTHENTICATION.md.
-- **docs/websocket_integration.md**, **docs/live_order_updates.md**: Notes updated for dynamic token, RenewToken, and API key/Partner in app.
-- **docs/standalone_ruby_websocket_integration.md**, **docs/rails_websocket_integration.md**: Configuration section updated with RenewToken and AUTHENTICATION.md link.
+- **docs/RAILS_INTEGRATION.md**: “Dynamic access token” section extended with RenewToken (web-generated tokens) and link to AUTHENTICATION.md.
+- **docs/WEBSOCKET_INTEGRATION.md**, **docs/LIVE_ORDER_UPDATES.md**: Notes updated for dynamic token, RenewToken, and API key/Partner in app.
+- **docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md**, **docs/RAILS_WEBSOCKET_INTEGRATION.md**: Configuration section updated with RenewToken and AUTHENTICATION.md link.
 
 ### CI / Release
 
@@ -112,8 +208,8 @@
 - **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.
-- **docs/rails_integration.md**: “Dynamic access token (optional)” with Rails initializer example.
-- **docs/websocket_integration.md**, **docs/live_order_updates.md**: Pointer to docs/AUTHENTICATION.md for dynamic token.
+- **docs/RAILS_INTEGRATION.md**: “Dynamic access token (optional)” with Rails initializer example.
+- **docs/WEBSOCKET_INTEGRATION.md**, **docs/LIVE_ORDER_UPDATES.md**: Pointer to docs/AUTHENTICATION.md for dynamic token.
 
 ### Backward compatibility
 

data/GUIDE.md

@@ -150,11 +150,11 @@ Example:
 
 ```ruby
 payload = {
-  transaction_type: "BUY",
-  exchange_segment: "NSE_EQ",
-  product_type: "CNC",
-  order_type: "LIMIT",
-  validity: "DAY",
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  validity: DhanHQ::Constants::Validity::DAY,
   security_id: "1333",
   quantity: 10,
   price: 150.0,
@@ -162,7 +162,7 @@ payload = {
 }
 
 order = DhanHQ::Models::Order.place(payload)
-puts order.order_status  # => "TRADED" / "PENDING" / ...
+puts order.order_status  # => DhanHQ::Constants::OrderStatus::TRADED / "PENDING" / ...
 ```
 
 ### Modification & Cancellation
@@ -193,10 +193,10 @@ Use the same fields as placement, but the contract allows additional validity op
 ```ruby
 slice_payload = {
   order_id: order.order_id,
-  transaction_type: "BUY",
-  exchange_segment: "NSE_EQ",
-  product_type: "STOP_LOSS",
-  order_type: "STOP_LOSS",
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::OrderType::STOP_LOSS,
+  order_type: DhanHQ::Constants::OrderType::STOP_LOSS,
   validity: "GTC",
   security_id: "1333",
   quantity: 100,
@@ -381,11 +381,11 @@ The response returns one object per super order with nested `leg_details`. Key a
 
 ```ruby
 params = {
-  transaction_type: "SELL",
-  exchange_segment: "NSE_EQ",
-  product_type: "CNC",
-  order_type: "LIMIT",
-  validity: "DAY",
+  transaction_type: DhanHQ::Constants::TransactionType::SELL,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  validity: DhanHQ::Constants::Validity::DAY,
   security_id: "1333",
   price: 200.0,
   trigger_price: 198.0
@@ -416,10 +416,10 @@ Convert an intraday position to delivery (or vice versa):
 ```ruby
 convert_payload = {
   security_id: "1333",
-  from_product_type: "INTRADAY",
-  to_product_type: "CNC",
+  from_product_type: DhanHQ::Constants::ProductType::INTRADAY,
+  to_product_type: DhanHQ::Constants::ProductType::CNC,
   convert_qty: 10,
-  exchange_segment: "NSE_EQ",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
   position_type: "LONG"
 }
 
@@ -496,8 +496,8 @@ Both endpoints return arrays and skip validation because they represent historic
 ```ruby
 bars = DhanHQ::Models::HistoricalData.intraday(
   security_id: "13",
-  exchange_segment: "IDX_I",
-  instrument: "INDEX",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::IDX_I,
+  instrument: DhanHQ::Constants::InstrumentType::INDEX,
   interval: "5",
   from_date: "2024-08-14",
   to_date: "2024-08-14"
@@ -509,13 +509,13 @@ bars = DhanHQ::Models::HistoricalData.intraday(
 ```ruby
 chain = DhanHQ::Models::OptionChain.fetch(
   underlying_scrip: 1333,
-  underlying_seg: "NSE_FNO",
+  underlying_seg: DhanHQ::Constants::ExchangeSegment::NSE_FNO,
   expiry: "2024-12-26"
 )
 
 expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
   underlying_scrip: 1333,
-  underlying_seg: "NSE_FNO"
+  underlying_seg: DhanHQ::Constants::ExchangeSegment::NSE_FNO
 )
 ```
 
@@ -527,10 +527,10 @@ The model filters strikes where both CE and PE have zero `last_price`, keeping t
 
 ```ruby
 params = {
-  exchange_segment: "NSE_EQ",
-  transaction_type: "BUY",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
   quantity: 10,
-  product_type: "INTRADAY",
+  product_type: DhanHQ::Constants::ProductType::INTRADAY,
   security_id: "1333",
   price: 150.0
 }
@@ -618,8 +618,8 @@ ws.on(:tick) do |tick|
   puts "[#{tick[:segment]} #{tick[:security_id]}] LTP=#{tick[:ltp]} kind=#{tick[:kind]}"
 end
 
-ws.subscribe_one(segment: "IDX_I", security_id: "13")
-ws.unsubscribe_one(segment: "IDX_I", security_id: "13")
+ws.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")
+ws.unsubscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")
 
 ws.disconnect!
 ```
@@ -643,17 +643,34 @@ If the credentials are invalid the helper raises `DhanHQ::InvalidAuthenticationE
 
 ### Alert Orders
 
+Condition must include `exchange_segment`, `exp_date`, and `frequency` per [conditional-trigger API](https://dhanhq.co/docs/v2/conditional-trigger/). For technical indicators, `time_frame` is also required.
+
 ```ruby
 # Model (CRUD)
 DhanHQ::Models::AlertOrder.all
 alert = DhanHQ::Models::AlertOrder.find("alert-id")
 alert = DhanHQ::Models::AlertOrder.create(
-  exchange_segment: "NSE_EQ",
-  security_id: "11536",
-  condition: "GTE",
-  trigger_price: 100.0,
-  transaction_type: "BUY",
-  quantity: 10
+  condition: {
+    security_id: "11536",
+    exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+    comparison_type: DhanHQ::Constants::ComparisonType::PRICE_WITH_VALUE,
+    operator: DhanHQ::Constants::Operator::GREATER_THAN,
+    comparing_value: 100.0,
+    exp_date: (Date.today + 365).strftime("%Y-%m-%d"),
+    frequency: "ONCE"
+  },
+  orders: [
+    {
+      transaction_type: DhanHQ::Constants::TransactionType::BUY,
+      exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+      product_type: DhanHQ::Constants::ProductType::CNC,
+      order_type: DhanHQ::Constants::OrderType::LIMIT,
+      security_id: "11536",
+      quantity: 10,
+      validity: DhanHQ::Constants::Validity::DAY,
+      price: 150.0
+    }
+  ]
 )
 alert.save
 alert.destroy
@@ -687,13 +704,14 @@ Params use snake_case; the client camelizes them before calling `/edis/...`.
 
 ### IP Setup
 
-Resource-only (account configuration) per API docs: GET /ip/getIP, POST /ip/setIP, PUT /ip/modifyIP.
+Resource-only (account configuration) per [API docs](https://dhanhq.co/docs/v2/authentication/#setup-static-ip): GET /ip/getIP, POST /ip/setIP, PUT /ip/modifyIP. Set/Modify require `dhanClientId`, `ip`, and `ipFlag` (PRIMARY or SECONDARY).
 
 ```ruby
 ip = DhanHQ::Resources::IPSetup.new
-ip.current              # GET /ip/getIP
-ip.set(ip: "103.21.58.121")
-ip.update(ip: "103.21.58.121")
+ip.current                                    # GET /ip/getIP
+ip.set(ip: "103.21.58.121")                   # ip_flag defaults to "PRIMARY", dhan_client_id from config
+ip.set(ip: "103.21.58.121", ip_flag: "SECONDARY")
+ip.update(ip: "103.21.58.121", ip_flag: "PRIMARY")
 ```
 
 ### Trader Control (Kill Switch)
@@ -709,7 +727,7 @@ tc.enable              # Trading resumed
 
 ### Kill Switch (model)
 
-Existing model API for backward compatibility:
+Uses query parameter per API doc: `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or DEACTIVATE), no body.
 
 ```ruby
 activate_payload   = DhanHQ::Models::KillSwitch.activate
@@ -725,7 +743,7 @@ DhanHQ::Models::KillSwitch.snake_case(deactivate_payload)
 DhanHQ::Models::KillSwitch.update("ACTIVATE")
 ```
 
-Only `"ACTIVATE"` and `"DEACTIVATE"` are accepted—any other value raises `DhanHQ::Error`. Use the `snake_case` helper to normalise API responses when you prefer underscore keys.
+Only `"ACTIVATE"` and `"DEACTIVATE"` are accepted. Use the `snake_case` helper to normalise API responses when you prefer underscore keys.
 
 ---