DhanHQ 3.2.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 287ad8c77adb3623574c0ee14102cfc3e88695168f75e1550a25dbbff9eb8508
-  data.tar.gz: a61b3f8e664f45f203b1afc3f840c9ed62a4e3c40e2f2d17fedc080ac682e029
+  metadata.gz: 065ac08985790dc4172816430025c482f539b506445c84181f69bdb56d30f510
+  data.tar.gz: 8f545f2ac8416dfadfe4fc0a5216b4203d06eaf05e1b1094d14ee571e84de342
 SHA512:
-  metadata.gz: 2c9ad1a3df906b585b0308809fb75235cf475a23c4eaddfea3f699de2e577819a1b78315b60012b6c51bb6c398dcaa35daab31d9ae9452d81d84e3e76741f0a9
-  data.tar.gz: 888e390276144b239a1bdd43afb9e77b58d21703587b898497b2426b8b78b47c7e03fd607bb3306fea49f9c2ae0e04a11ccb1b6968fc109fe61a8d2627b750a4
+  metadata.gz: 27d821b96f67997c64f1a523c2a366736dabcea5175e621014e22c9b691f35835f008f3bacaefe6b26229d2de92a78d44719f1b5ebff3e288960f156f7192331
+  data.tar.gz: 76558d36116bbc9c2b024aacc0c6cb1c30640b777cf2cd0832cb6d8da9b142fd6aca350318489a3d13f848136c1089bcd1ef014a2a975c8f66bde1e7c8131d10

data/CHANGELOG.md

@@ -1,3 +1,51 @@
+## [3.3.0] - 2026-07-26
+
+### Added
+
+- **Bang variants for every write method with a falsy failure contract** — `Order.place!`, `Order#modify!`/`#cancel!`/`#refresh!`, `SuperOrder.create!`/`#modify!`/`#cancel!`, `ForeverOrder.create!`, `IcebergOrder.create!`, `TwapOrder.create!`, `AlertOrder.create!`/`.modify!`, `PnlExit.configure!`/`.stop!`, `MultiOrder.place!`, `GlobalStocks::Order.place!`/`#modify!`/`#cancel!`.
+
+  Each raises `DhanHQ::OrderError` — which descends from `DhanHQ::Error`, so an existing `rescue DhanHQ::Error` handler still catches it — carrying whatever diagnostics the failure held. The non-bang methods are **untouched**: they return exactly what they returned before, so no existing caller changes behaviour.
+
+  This is step one of unifying the write return contracts. Today those contracts disagree: depending on the class and the failure, a rejected write comes back as `nil`, as `false`, or as a `DhanHQ::ErrorObject`, and `AlertOrder.modify` can return either of the first two from the same method. A caller cannot write one error branch. Unifying them outright would be a silent breaking change for dependent applications, because `nil` and `false` are falsy while `ErrorObject` is truthy — every `if result` failure branch in a dependent would quietly invert. So the migration is staged:
+
+  1. **This release** — additive bang variants. Opt in per call site.
+  2. **This release** — log a deprecation whenever a non-bang write returns a falsy failure, to find the remaining call sites from dependents' logs.
+  3. **4.0.0** — non-bang methods return `ErrorObject` uniformly, gated on step 2 going quiet.
+
+- **Deprecation notices for ambiguous write failures** (step two). When a non-bang write returns `nil`, `false` or a `DhanHQ::ErrorObject`, the SDK now logs once per call site:
+
+  ```
+  [DhanHQ] DEPRECATION: DhanHQ::Models::Order.place reported failure as nil. Write
+  methods return nil, false or a DhanHQ::ErrorObject inconsistently today and will all
+  return DhanHQ::ErrorObject in 4.0.0, which is truthy — an `if result` failure branch
+  will invert. Use DhanHQ::Models::Order.place! to get a DhanHQ::OrderError instead...
+  ```
+
+  The point is to surface the remaining call sites from dependent applications' logs before 4.0.0 changes any return value. Once per call site per process, not once per failure — a session that rejects hundreds of orders would otherwise produce noise that gets filtered out, defeating the purpose.
+
+  This layer only observes: it never alters a return value and never raises. It is silent on success, silent when reached through a bang variant (those callers have already migrated), and silent when you set `config.warn_on_ambiguous_write_failure = false` / `DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false`. Defaults to on, because a notice nobody sees finds nothing.
+
+- **`DhanHQ::Concerns::TrackedWrites`** — installs the observation. Uses `prepend` rather than `include`, since the write methods are defined directly on the model classes and an included module would sit behind them in the ancestor chain and never be reached.
+- **`DhanHQ::Deprecation`** — once-per-key notice registry, thread-safe, with `warned_keys` and `reset!` for tests.
+- **`DhanHQ::WriteResult`** — puts the knowledge of what a write failure looks like in one place (`failure?`, `success?`, `unwrap!`). `BaseModel#save!` now uses it instead of duplicating the same three-way check inline.
+- **`DhanHQ::Concerns::BangWrites`** — generates the bang variants by delegating to their non-bang counterparts, so the two cannot drift: no duplicated request building, validation or logging. Generated as a module, so a hand-written `place!` can still override and call `super`.
+
+### Fixed
+
+- **`DhanHQ::MCP` was unreachable on a bare `require "dhan_hq"`.** Same failure as the `DhanHQ::AI` fix earlier in this release: `mcp.rb` defines `DhanHQ::MCP` while Zeitwerk's inflector expected `DhanHQ::Mcp` from the filename, so `DhanHQ::MCP::Server` raised `NameError` unless something had already loaded the file by hand — which only `exe/dhanhq-mcp` and `lib/dhan_hq/mcp.rb` did. Found the same way the `AI` bug was: cross-referencing every `DhanHQ::` constant named in the docs against what actually resolves. Guarded by a new `spec/dhan_hq/zeitwerk_autoload_spec.rb`, which shells out to a subprocess so the check can't be satisfied by another spec having already loaded the file by hand.
+- **`lib/DhanHQ/configuration.rb`'s doc comment referenced `DhanHQ::Models::Order.find_by_correlation_id`, which does not exist** — the real method is `.find_by_correlation` (no `_id` suffix). Caught during the same audit.
+- A documentation pass across the gem ahead of this release, cross-checking every code example and referenced class/method against the actual codebase:
+  - `docs/CONFIGURATION.md`'s resource table named `DhanHQ::Models::Fund` (real class: `Funds`) and `DhanHQ::Models::Ledger` (real class: `LedgerEntry`), and listed `fund_limit`/`margin_calculator` as `Funds` methods — neither exists; the real methods are `Funds.fetch`/`.balance` and `Margin.calculate`/`.calculate_multi`. The table now also covers the resources 3.2.0/3.3.0 added (Iceberg/TWAP/Alert orders, Multi Order, P&L Exit, eDIS, Global Stocks) and lists the `!` write variants.
+  - `docs/CONFIGURATION.md` was missing `LIVE_TRADING`, `DHAN_DRY_RUN`, `DHAN_RETRY_WRITES`, `DHAN_AUTO_CORRELATION_ID`, `DHAN_WARN_AMBIGUOUS_WRITE_FAILURE` and `DHAN_MARKET_DEPTH_LEVEL` entirely, and documented `DHAN_LOG_LEVEL` as if the library read it automatically — it doesn't; only the existing `## Logging` snippet wires it up.
+  - `skills/dhanhq-ruby/references/portfolio.md`'s eDIS section had the class name miscased (`EDIS` vs. `Edis`), called a nonexistent `.open_browser_for_tpin`, called `.inquiry` instead of `.inquire`, and accessed the (Hash) result via method calls instead of keys.
+  - `README.md` called `DhanHQ::Models::Fund.balance` — same class-name typo as above.
+  - `docs/RELEASE_GUIDE.md` claimed `Required Ruby: >= 3.1.0`; the gemspec has required `>= 3.2.0` since 3.0.0.
+  - `GUIDE.md` had no mention of the bang write variants added in this release; added a short section pointing to the README's fuller treatment.
+
+### Changed
+
+- `BaseModel#save!`'s exception message is now `"<Class>#save failed: <details>"` rather than `"Failed to save the record: <details>"`. The exception class is unchanged (`DhanHQ::Error`), and nothing in the gem, specs or docs asserted the old text.
+
 ## [3.2.1] - 2026-07-26
 
 ### Fixed

data/GUIDE.md

@@ -186,6 +186,22 @@ DhanHQ::Contracts::ModifyOrderContract.new.call(params).success?
 DhanHQ::Models::Order.resource.update("123", params)
 ```
 
+### Explicit Failures: Bang Variants
+
+`place`, `#modify`, `#cancel` and their equivalents across every write model do not agree on
+how they report failure — depending on the class, a rejected write comes back as `nil`,
+`false`, or a `DhanHQ::ErrorObject`. Each has a `!` variant that raises `DhanHQ::OrderError`
+instead, so one `rescue` handles every failure the same way:
+
+```ruby
+order = DhanHQ::Models::Order.place!(params)   # raises DhanHQ::OrderError on failure
+order.cancel!                                  # raises if the exchange did not cancel
+```
+
+The non-bang methods are unchanged — adopting the bang variant is opt-in, per call site.
+See the [README](README.md#explicit-failures-bang-variants) for the full list of `!` methods
+and the deprecation notice that flags remaining non-bang call sites ahead of 4.0.0.
+
 ### Slicing Orders
 
 Use the same fields as placement, but the contract allows additional validity options (`GTC`, `GTD`). The model helper accepts snake_case parameters and handles camelCase conversion as part of validation:

data/README.md

@@ -314,6 +314,59 @@ risk:
 DhanHQ.configure { |config| config.retry_non_idempotent_writes = true }
 ```
 
+### Explicit Failures: Bang Variants
+
+Every write method has a `!` variant that raises instead of returning a falsy value:
+
+```ruby
+order = DhanHQ::Models::Order.place!(params)   # raises DhanHQ::OrderError on failure
+order.cancel!                                  # raises if the exchange did not cancel
+```
+
+This exists because the non-bang methods do not agree on how to report failure — some
+return `nil`, some `false`, some a `DhanHQ::ErrorObject` — so a caller cannot write one
+error branch:
+
+```ruby
+# Before: which falsy thing came back depends on which method and which failure
+order = DhanHQ::Models::Order.place(params)
+return unless order            # nil on rejection
+
+result = DhanHQ::Models::MultiOrder.place(legs)
+return if result.is_a?(DhanHQ::ErrorObject)   # truthy! `unless result` would not catch this
+```
+
+`DhanHQ::OrderError` descends from `DhanHQ::Error`, so an existing `rescue DhanHQ::Error`
+keeps working. The non-bang methods are unchanged, so adopting this is per call site:
+
+```ruby
+begin
+  DhanHQ::Models::Order.place!(params)
+rescue DhanHQ::OrderError => e
+  logger.error(e.message)   # carries the API's diagnostics
+end
+```
+
+When a non-bang write reports failure, the SDK logs once per call site to help you find
+what needs migrating before 4.0.0 changes the return value:
+
+```
+[DhanHQ] DEPRECATION: DhanHQ::Models::Order.place reported failure as nil. ...
+Use DhanHQ::Models::Order.place! to get a DhanHQ::OrderError instead, or set
+config.warn_on_ambiguous_write_failure = false to silence this.
+```
+
+It fires once per call site per process, never alters a return value, never raises, and
+goes quiet once you switch that site to the bang variant. To silence it entirely:
+
+```ruby
+DhanHQ.configure { |c| c.warn_on_ambiguous_write_failure = false }   # or DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false
+```
+
+Available on `Order`, `SuperOrder`, `ForeverOrder`, `IcebergOrder`, `TwapOrder`,
+`AlertOrder`, `PnlExit`, `MultiOrder` and `GlobalStocks::Order`. The non-bang methods are
+planned to converge on `ErrorObject` in 4.0.0 — see the CHANGELOG for the staged plan.
+
 ### Order Audit Logging
 
 Every order attempt (place, modify, slice) automatically logs a structured JSON line at WARN level:
@@ -374,7 +427,7 @@ order.cancel
 ```ruby
 DhanHQ::Models::Position.all
 DhanHQ::Models::Holding.all
-DhanHQ::Models::Fund.balance
+DhanHQ::Models::Funds.balance
 ```
 
 ### Historical Data

data/docs/CONFIGURATION.md

@@ -24,7 +24,6 @@ Set these _before_ calling `configure_with_env` to override defaults:
 
 | Variable                         | Default    | Description                                             |
 | -------------------------------- | ---------- | ------------------------------------------------------- |
-| `DHAN_LOG_LEVEL`                 | `INFO`     | Logger verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`)     |
 | `DHAN_SANDBOX`                   | `false`    | Set `"true"` to route REST calls to `https://sandbox.dhan.co/v2` instead of production. Note: Dhan's sandbox validates request/response plumbing only — it does not execute real order fills/matching. Placed orders stay `PENDING` indefinitely. See [ENDPOINTS_AND_SANDBOX.md](ENDPOINTS_AND_SANDBOX.md). |
 | `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname. Takes precedence over `DHAN_SANDBOX` only when explicitly set to something other than the production default. |
 | `DHAN_WS_VERSION`                | latest     | Pin WebSocket connections to a specific API version     |
@@ -32,12 +31,27 @@ Set these _before_ calling `configure_with_env` to override defaults:
 | `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_MARKET_DEPTH_LEVEL`        | `20`       | WebSocket market depth levels to subscribe to           |
 | `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)    |
 
+`DHAN_LOG_LEVEL` is **not** read automatically — see [Logging](#logging) below for the one-line snippet that wires it up.
+
+## Behavior Flags
+
+These change what a write request *does*, not just where it goes. All default to the safe/conservative behavior and are off unless set.
+
+| Variable                             | Config attribute                    | Default | Effect |
+| ------------------------------------- | ------------------------------------ | ------- | ------ |
+| `LIVE_TRADING=true`                   | —                                    | unset   | **Required to place, modify, or cancel any real order, position exit, kill switch, EDIS, or P&L exit.** Without it, every write-path resource raises `DhanHQ::LiveTradingDisabledError` before making the request. This is the primary safety gate — see [ARCHITECTURE.md](../ARCHITECTURE.md) and the risk pipeline. |
+| `DHAN_DRY_RUN=true`                    | `config.dry_run`                     | `false` | Suppresses every state-changing request, logs the payload as `DHAN_DRY_RUN`, and answers order placements with a simulated `DRYRUN-…` id so caller code paths still run to completion. Reads still hit the API. |
+| `DHAN_RETRY_WRITES=true`               | `config.retry_non_idempotent_writes` | `false` | Auto-retries a non-idempotent write (order placement, modify, cancel) after a transient failure (429, 5xx, timeout). Off by default because the API has no idempotency key — a timed-out POST may have already reached the exchange, and retrying it can place a duplicate order. |
+| `DHAN_AUTO_CORRELATION_ID=true`        | `config.auto_correlation_id`         | `false` | Fills in a `correlationId` (`dhq-<hex>`) on order placements that lack one, so a timed-out placement can be reconciled via `GET /v2/orders/external/{correlation-id}`. Off by default because it changes the request body; an explicit correlation id is always preserved. |
+| `DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false` | `config.warn_on_ambiguous_write_failure` | `true` (on) | Logs a once-per-call-site deprecation notice when a non-bang write method (`Order.place`, `#modify`, …) reports failure as `nil`, `false`, or a `DhanHQ::ErrorObject` — these disagree today and unify on `ErrorObject` in 4.0.0. Use the `!` variant (`place!`, `#modify!`) to get a raised `DhanHQ::OrderError` instead of the ambiguous return value. |
+
 ## `.env` File Setup
 
 Create a `.env` file in your project root:
@@ -95,16 +109,26 @@ 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`                 |
+| Resource                 | Model                                   | Actions                                                                       |
+| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------ |
+| Orders                   | `DhanHQ::Models::Order`                 | `place`, `find`, `all`, `where`, `#modify`, `#cancel`, `#destroy` (`!` variants raise) |
+| Trades                   | `DhanHQ::Models::Trade`                 | `all`, `find_by_order_id`                                                     |
+| Forever Orders           | `DhanHQ::Models::ForeverOrder`          | `create`, `find`, `all`, `#modify`, `#cancel`                                 |
+| Iceberg Orders           | `DhanHQ::Models::IcebergOrder`          | `create`, `find`, `all`, `#modify`, `#cancel`                                 |
+| TWAP Orders              | `DhanHQ::Models::TwapOrder`             | `create`, `find`, `all`, `#modify`, `#cancel`                                 |
+| Alert Orders             | `DhanHQ::Models::AlertOrder`            | `create`, `find`, `all`, `modify(alert_id, params)`, `#destroy`               |
+| Super Orders             | `DhanHQ::Models::SuperOrder`            | `create`, `all`, `#modify`, `#cancel(leg_name)`                               |
+| Multi Order (basket)     | `DhanHQ::Models::MultiOrder`            | `place(orders, dhan_client_id:)` — up to 15 legs                              |
+| P&L Exit                 | `DhanHQ::Models::PnlExit`               | `configure`, `stop`, `status`                                                 |
+| Holdings                 | `DhanHQ::Models::Holding`               | `all`                                                                         |
+| Positions                | `DhanHQ::Models::Position`              | `all`, `active`, `#convert(params)`, `.exit_all!`                             |
+| Funds                    | `DhanHQ::Models::Funds`                 | `fetch`, `balance`                                                            |
+| Margin Calculator        | `DhanHQ::Models::Margin`                | `calculate(params)`, `calculate_multi(params)`                                |
+| Ledger                   | `DhanHQ::Models::LedgerEntry`           | `all(from_date:, to_date:)`                                                   |
+| eDIS                     | `DhanHQ::Models::Edis`                  | `generate_tpin`, `generate_form`, `generate_bulk_form`, `inquire(isin:)`      |
+| 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`                                                  |
+| Global Stocks Orders     | `DhanHQ::Models::GlobalStocks::Order`   | `place`, `find`, `all`, `#cancel` — see [ARCHITECTURE.md](../ARCHITECTURE.md) |
+
+`#method` denotes an instance method (called on a fetched or created record); everything else is a class method. Every write method above also has a `!` variant (`place!`, `#modify!`, `#cancel!`, …) that raises `DhanHQ::OrderError` instead of returning a falsy value or an `ErrorObject` — see the [CHANGELOG](../CHANGELOG.md) for the write-return-contract migration this is part of.

data/docs/RELEASE_GUIDE.md

@@ -434,7 +434,7 @@ git push origin main v2.1.12
 
 - **Gem Name:** DhanHQ
 - **Current Version:** Check `lib/DhanHQ/version.rb`
-- **Required Ruby:** >= 3.1.0
+- **Required Ruby:** >= 3.2.0
 - **License:** MIT
 - **Homepage:** https://github.com/shubhamtaywade82/dhanhq-client
 

data/lib/DhanHQ/concerns/bang_writes.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../write_result"
+
+module DhanHQ
+  module Concerns
+    # Generates bang variants of write methods that raise instead of returning a falsy
+    # value or an {DhanHQ::ErrorObject}.
+    #
+    # Each generated method calls its non-bang counterpart and passes the result through
+    # {DhanHQ::WriteResult.unwrap!}, so the two cannot drift: there is no duplicated
+    # request building, validation or logging. The non-bang methods are untouched, which
+    # is what makes this additive — existing callers keep the return values they were
+    # written against.
+    #
+    # @example
+    #   class Order < BaseModel
+    #     extend DhanHQ::Concerns::BangWrites
+    #
+    #     bang_class_writes :place        # defines Order.place!
+    #     bang_writes :modify, :cancel    # defines #modify! and #cancel!
+    #   end
+    #
+    #   Order.place!(params)   # => Order, or raises DhanHQ::OrderError
+    #   order.cancel!          # => true,  or raises DhanHQ::OrderError
+    module BangWrites
+      # Defines `<name>!` instance methods.
+      #
+      # @param names [Array<Symbol>] Existing instance write methods to wrap.
+      # @param error_class [Class] Exception the generated methods raise.
+      # @return [void]
+      def bang_writes(*names, error_class: DhanHQ::OrderError)
+        names.each { |name| include bang_write_module(name, error_class) }
+      end
+
+      # Defines `<name>!` class methods.
+      #
+      # @param names [Array<Symbol>] Existing class write methods to wrap.
+      # @param error_class [Class] Exception the generated methods raise.
+      # @return [void]
+      def bang_class_writes(*names, error_class: DhanHQ::OrderError)
+        names.each { |name| singleton_class.include bang_write_module(name, error_class) }
+      end
+
+      private
+
+      # Built as a module rather than defined directly, so a hand-written `place!` in
+      # the class body still overrides the generated one and can call `super`.
+      def bang_write_module(name, error_class)
+        Module.new do
+          define_method(:"#{name}!") do |*args, **kwargs, &block|
+            # A caller already using the bang variant does not need a deprecation
+            # notice telling them to use the bang variant.
+            result = DhanHQ::WriteResult.suppressing_deprecation do
+              public_send(name, *args, **kwargs, &block)
+            end
+
+            DhanHQ::WriteResult.unwrap!(
+              result,
+              operation: DhanHQ::WriteResult.operation_label(self, name),
+              error_class: error_class,
+              errors: DhanHQ::WriteResult.errors_from(self)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/concerns/tracked_writes.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../write_result"
+
+module DhanHQ
+  module Concerns
+    # Observes non-bang write methods and reports, once per call site, when one returns
+    # a failure shape that 4.0.0 will change.
+    #
+    # Uses +prepend+ rather than +include+ because these methods are defined directly on
+    # the model classes: an included module sits behind the class in the ancestor chain
+    # and would never be reached. A prepended one sits in front, so +super+ runs the real
+    # method and the result passes through untouched.
+    #
+    # This layer only observes. It never changes a return value, never raises, and goes
+    # quiet once a call site has been migrated to the bang variant.
+    #
+    # @example
+    #   class Order < BaseModel
+    #     extend DhanHQ::Concerns::TrackedWrites
+    #
+    #     track_class_writes :place        # warns when Order.place returns nil
+    #     track_writes :modify, :cancel    # warns when #cancel returns false
+    #   end
+    module TrackedWrites
+      # Observes `<name>` instance methods.
+      #
+      # @param names [Array<Symbol>] Existing instance write methods to observe.
+      # @return [void]
+      def track_writes(*names)
+        names.each { |name| prepend tracking_module(name) }
+      end
+
+      # Observes `<name>` class methods.
+      #
+      # @param names [Array<Symbol>] Existing class write methods to observe.
+      # @return [void]
+      def track_class_writes(*names)
+        names.each { |name| singleton_class.prepend tracking_module(name) }
+      end
+
+      private
+
+      def tracking_module(name)
+        Module.new do
+          define_method(name) do |*args, **kwargs, &block|
+            DhanHQ::WriteResult.report_ambiguous_failure(
+              super(*args, **kwargs, &block),
+              operation: DhanHQ::WriteResult.operation_label(self, name)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/configuration.rb

@@ -60,7 +60,7 @@ module DhanHQ
     # /v2/orders that times out may well have reached the exchange, and retrying it
     # can place a second, duplicate order. With this off, the transient error is
     # raised to the caller, who can reconcile using the correlation id (see
-    # {#auto_correlation_id} and +DhanHQ::Models::Order.find_by_correlation_id+)
+    # {#auto_correlation_id} and +DhanHQ::Models::Order.find_by_correlation+)
     # before deciding to resubmit.
     #
     # Read requests are always retried regardless of this setting.
@@ -69,6 +69,19 @@ module DhanHQ
     # @return [Boolean]
     attr_accessor :retry_non_idempotent_writes
 
+    # Whether to log a deprecation notice, once per call site, when a non-bang write
+    # method reports failure through +nil+, +false+ or a {DhanHQ::ErrorObject}.
+    #
+    # Those contracts disagree today and will unify on {DhanHQ::ErrorObject} in 4.0.0,
+    # which is truthy — so an `if result` failure branch written against +nil+ or
+    # +false+ will silently invert. The notice names the call sites that need moving to
+    # a bang variant before then.
+    #
+    # Defaults to +true+: a notice nobody sees finds nothing. Set to +false+ once the
+    # call sites are migrated, or via +DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false+.
+    # @return [Boolean]
+    attr_accessor :warn_on_ambiguous_write_failure
+
     # Whether to generate a +correlationId+ for order placements that do not carry
     # one. The correlation id is the only way to answer "did my order actually go
     # through?" after a timeout, via GET /v2/orders/external/{correlation-id}.
@@ -175,6 +188,11 @@ module DhanHQ
       @retry_non_idempotent_writes == true
     end
 
+    # @return [Boolean] True when ambiguous write failures should be reported.
+    def warn_on_ambiguous_write_failure?
+      @warn_on_ambiguous_write_failure == true
+    end
+
     # @return [Boolean] True when a correlation id should be generated for orders.
     def auto_correlation_id?
       @auto_correlation_id == true
@@ -193,6 +211,7 @@ module DhanHQ
       @dry_run        = env_flag("DHAN_DRY_RUN", default: false)
       @retry_non_idempotent_writes = env_flag("DHAN_RETRY_WRITES", default: false)
       @auto_correlation_id = env_flag("DHAN_AUTO_CORRELATION_ID", default: false)
+      @warn_on_ambiguous_write_failure = env_flag("DHAN_WARN_AMBIGUOUS_WRITE_FAILURE", default: true)
       @base_url       = ENV.fetch("DHAN_BASE_URL", nil)
       @ws_version     = ENV.fetch("DHAN_WS_VERSION", 2).to_i
       @ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", nil)

data/lib/DhanHQ/core/base_model.rb

@@ -193,19 +193,12 @@ module DhanHQ
     # @return [DhanHQ::BaseModel]
     # @raise [DhanHQ::Error] When the record cannot be saved.
     def save!
-      result = save
-      return result unless result == false || result.nil? || result.is_a?(DhanHQ::ErrorObject)
-
-      error_details =
-        if result.is_a?(DhanHQ::ErrorObject)
-          result.errors
-        elsif @errors && !@errors.empty?
-          @errors
-        else
-          "Unknown error"
-        end
-
-      raise DhanHQ::Error, "Failed to save the record: #{error_details}"
+      DhanHQ::WriteResult.unwrap!(
+        save,
+        operation: "#{self.class}#save",
+        error_class: DhanHQ::Error,
+        errors: @errors
+      )
     end
 
     # Delete the resource

data/lib/DhanHQ/deprecation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Emits a deprecation notice once per call site per process.
+  #
+  # A trading process can reject hundreds of orders in a session. A notice that fires
+  # on every one of them is noise that gets filtered out, which defeats the purpose —
+  # the point is for a maintainer to find the handful of call sites still relying on
+  # behaviour that is going to change, then fix them.
+  module Deprecation
+    @warned = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Logs +message+ the first time this +key+ is seen in this process.
+      #
+      # A command, not a query: callers that need to know whether a notice was emitted
+      # should consult {.warned_keys}.
+      #
+      # @param key [String, Symbol] Identifies the call site, e.g. the operation name.
+      # @param message [String] What is deprecated and what to do instead.
+      # @return [void]
+      def warn_once(key, message)
+        return unless first_warning_for?(key)
+
+        DhanHQ.logger&.warn("[DhanHQ] DEPRECATION: #{message}")
+        nil
+      end
+
+      # Keys already warned about, for assertions and diagnostics.
+      #
+      # @return [Array<String>]
+      def warned_keys
+        @mutex.synchronize { @warned.keys }
+      end
+
+      # Forgets every emitted notice, so the next occurrence warns again.
+      # Intended for test isolation.
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize { @warned.clear }
+      end
+
+      private
+
+      # Whether this is the first time +key+ has been seen, recording it either way.
+      #
+      # The check and the record happen under one lock so two threads hitting the same
+      # call site at once cannot both decide they are first.
+      #
+      # @return [Boolean]
+      def first_warning_for?(key)
+        @mutex.synchronize do
+          next false if @warned.key?(key.to_s)
+
+          @warned[key.to_s] = true
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/alert_order.rb

@@ -6,6 +6,13 @@ module DhanHQ
   module Models
     # Model for alert/conditional orders. CRUD via AlertOrders resource; validated by AlertOrderContract.
     class AlertOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create, :modify
+
+      bang_class_writes :create, :modify
+
       include Concerns::ApiResponseHandler
 
       HTTP_PATH = "/v2/alerts/orders"

data/lib/DhanHQ/models/forever_order.rb

@@ -66,6 +66,15 @@ module DhanHQ
     #   orders.each { |order| puts order.order_status }
     #
     class ForeverOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :create
+      bang_writes :modify, :cancel
+
       include Concerns::ApiResponseHandler
 
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,

data/lib/DhanHQ/models/global_stocks/order.rb

@@ -36,6 +36,15 @@ module DhanHQ
       #   end
       #
       class Order < BaseModel
+        extend DhanHQ::Concerns::BangWrites
+        extend DhanHQ::Concerns::TrackedWrites
+
+        track_class_writes :place
+        track_writes :modify, :cancel
+
+        bang_class_writes :place
+        bang_writes :modify, :cancel
+
         HTTP_PATH = "/v2/globalstocks/orders"
 
         attributes :dhan_client_id, :order_id, :exchange_order_id, :correlation_id,

data/lib/DhanHQ/models/iceberg_order.rb

@@ -48,6 +48,15 @@ module DhanHQ
     #   orders = DhanHQ::Models::IcebergOrder.all
     #
     class IcebergOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :create
+      bang_writes :modify, :cancel
+
       include Concerns::ApiResponseHandler
 
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,

data/lib/DhanHQ/models/multi_order.rb

@@ -26,6 +26,13 @@ module DhanHQ
     #   result.for_sequence("1").order_id
     #
     class MultiOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :place
+
+      bang_class_writes :place
+
       HTTP_PATH = "/v2/alerts/multi/orders"
 
       attributes :orders

data/lib/DhanHQ/models/order.rb

@@ -46,6 +46,15 @@ module DhanHQ
     #   puts "Pending orders: #{pending_orders.count}"
     #
     class Order < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :place, :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :place, :create
+      bang_writes :modify, :cancel, :refresh
+
       include Concerns::ApiResponseHandler
 
       # Attributes eligible for modification requests.
@@ -430,6 +439,25 @@ module DhanHQ
           order.save # calls resource create or update
           order
         end
+
+        # `create` always returns the built `Order`, even when `#save` returned
+        # `false` -- existing callers rely on that to inspect an unsaved order's
+        # `errors`, so `create` cannot change. The generated `create!` would
+        # therefore call `unwrap!` on an object that is truthy regardless of
+        # whether the placement actually succeeded, and never raise. This
+        # hand-written override supersedes it (see {BangWrites} for why a
+        # class-body definition takes precedence) and unwraps on `persisted?`
+        # instead, which reflects whether the API actually accepted the order.
+        def create!(params)
+          order = DhanHQ::WriteResult.suppressing_deprecation { create(params) }
+
+          DhanHQ::WriteResult.unwrap!(
+            order.persisted? ? order : false,
+            operation: DhanHQ::WriteResult.operation_label(self, :create),
+            error_class: DhanHQ::OrderError,
+            errors: DhanHQ::WriteResult.errors_from(order)
+          )
+        end
       end
 
       ##

data/lib/DhanHQ/models/pnl_exit.rb

@@ -32,6 +32,13 @@ module DhanHQ
     #   puts response[:pnl_exit_status] # => "DISABLED"
     #
     class PnlExit < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :configure, :stop
+
+      bang_class_writes :configure, :stop
+
       HTTP_PATH = "/v2/pnlExit"
 
       attributes :pnl_exit_status, :profit, :loss, :segments, :enable_kill_switch

data/lib/DhanHQ/models/super_order.rb

@@ -48,6 +48,15 @@ module DhanHQ
     #   order.cancel("STOP_LOSS_LEG")
     #
     class SuperOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :create
+      bang_writes :modify, :cancel
+
       include Concerns::ApiResponseHandler
 
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,

data/lib/DhanHQ/models/twap_order.rb

@@ -45,6 +45,15 @@ module DhanHQ
     #   order.cancel
     #
     class TwapOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :create
+      bang_writes :modify, :cancel
+
       include Concerns::ApiResponseHandler
 
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "3.2.1"
+  VERSION = "3.3.0"
 end

data/lib/DhanHQ/write_result.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Interprets the several shapes a write currently uses to signal failure.
+  #
+  # The model write methods do not share a return contract. Depending on which class
+  # and which failure you hit, a rejected write comes back as +nil+, as +false+, or as
+  # a {DhanHQ::ErrorObject} — and {DhanHQ::Models::AlertOrder.modify} can return either
+  # of the first two from the same method. A caller cannot write one error branch.
+  #
+  # Unifying those contracts is a breaking change for the applications that depend on
+  # this gem, so it is staged (see CHANGELOG). This module is step one: it puts the
+  # knowledge of "what does failure look like" in exactly one place, and backs the bang
+  # variants (+place!+, +modify!+, +cancel!+, …) that give callers a single, explicit
+  # failure mode to rescue today.
+  #
+  # @example Opting a call site into explicit failures
+  #   order = DhanHQ::Models::Order.place!(params)   # raises DhanHQ::OrderError
+  #   # instead of
+  #   order = DhanHQ::Models::Order.place(params)    # nil on failure
+  module WriteResult
+    # Thread-local flag set while a bang variant is calling through.
+    SUPPRESSION_KEY = :dhanhq_suppress_write_deprecation
+
+    module_function
+
+    # Whether a write result represents a rejected or failed operation.
+    #
+    # @param result [Object] Return value of a write method.
+    # @return [Boolean]
+    def failure?(result)
+      result.nil? || result == false || result.is_a?(DhanHQ::ErrorObject)
+    end
+
+    # @param result [Object] Return value of a write method.
+    # @return [Boolean]
+    def success?(result)
+      !failure?(result)
+    end
+
+    # Returns the result, or raises carrying whatever diagnostics the failure held.
+    #
+    # @param result [Object] Return value of a write method.
+    # @param operation [String] Human-readable operation name for the message,
+    #   e.g. +"DhanHQ::Models::Order.place"+.
+    # @param error_class [Class] Exception to raise. Defaults to {DhanHQ::OrderError},
+    #   which descends from {DhanHQ::Error}, so existing `rescue DhanHQ::Error`
+    #   handlers still catch it.
+    # @param errors [Hash, nil] Validation errors to report when the result itself
+    #   carries none — typically a model's +errors+ hash.
+    # @return [Object] The result, when it represents success.
+    # @raise [DhanHQ::Error] When the result represents failure.
+    def unwrap!(result, operation:, error_class: DhanHQ::OrderError, errors: nil)
+      return result if success?(result)
+
+      raise error_class, "#{operation} failed: #{describe(result, errors)}"
+    end
+
+    # Reports, once per call site, that a non-bang write signalled failure through a
+    # value whose shape is going to change in 4.0.0.
+    #
+    # Step two of the migration: the notice tells a maintainer which of their call
+    # sites still branch on the old return value, so they can move to the bang variant
+    # before the non-bang contract unifies on {DhanHQ::ErrorObject}. Returns the result
+    # untouched — this observes, it never alters behaviour.
+    #
+    # Silent when the write succeeded, when the caller opted out via
+    # +config.warn_on_ambiguous_write_failure = false+, or when reached through a bang
+    # variant (those callers have already migrated — see {.suppressing_deprecation}).
+    #
+    # @param result [Object] Return value of a non-bang write method.
+    # @param operation [String] Operation label from {.operation_label}.
+    # @return [Object] The result, unchanged.
+    def report_ambiguous_failure(result, operation:)
+      return result unless failure?(result)
+      return result if suppressed?
+      return result unless DhanHQ.configuration&.warn_on_ambiguous_write_failure?
+
+      DhanHQ::Deprecation.warn_once(
+        operation,
+        "#{operation} reported failure as #{shape_of(result)}. Write methods return " \
+        "nil, false or a DhanHQ::ErrorObject inconsistently today and will all return " \
+        "DhanHQ::ErrorObject in 4.0.0, which is truthy — an `if result` failure branch " \
+        "will invert. Use #{operation}! to get a DhanHQ::OrderError instead, or set " \
+        "config.warn_on_ambiguous_write_failure = false to silence this."
+      )
+
+      result
+    end
+
+    # Runs the block with {.report_ambiguous_failure} disabled on this thread.
+    #
+    # Used by the bang variants: they call the non-bang method to get its result, and a
+    # caller who has already moved to `place!` does not need telling to move to
+    # `place!`. Thread-local so a concurrent thread still gets its own notices.
+    #
+    # @return [Object] The block's value.
+    def suppressing_deprecation
+      previous = Thread.current[SUPPRESSION_KEY]
+      Thread.current[SUPPRESSION_KEY] = true
+      yield
+    ensure
+      Thread.current[SUPPRESSION_KEY] = previous
+    end
+
+    # @return [Boolean]
+    def suppressed?
+      Thread.current[SUPPRESSION_KEY] == true
+    end
+
+    # Names the shape a failure arrived in, for the notice.
+    #
+    # @return [String]
+    def shape_of(result)
+      return "nil" if result.nil?
+      return "false" if result == false
+
+      "a DhanHQ::ErrorObject"
+    end
+
+    # Label identifying the operation that failed, for the exception message.
+    #
+    # @param receiver [Object] The class (for a class method) or instance.
+    # @param name [Symbol] Method name.
+    # @return [String] e.g. +"DhanHQ::Models::Order.place"+ or +"…Order#modify"+.
+    def operation_label(receiver, name)
+      return "#{module_label(receiver)}.#{name}" if receiver.is_a?(Module)
+
+      "#{module_label(receiver.class)}##{name}"
+    end
+
+    # Reads a module's declared name, falling back to +to_s+ so an anonymous class
+    # still yields something readable rather than an object address.
+    #
+    # @return [String]
+    def module_label(mod)
+      mod.name || mod.to_s
+    end
+
+    # Validation errors carried by a model instance, when it has any.
+    #
+    # @param receiver [Object]
+    # @return [Hash, nil]
+    def errors_from(receiver)
+      return nil if receiver.is_a?(Module)
+      return nil unless receiver.respond_to?(:errors)
+
+      receiver.errors
+    end
+
+    # Best available explanation for a failure.
+    #
+    # @return [String]
+    def describe(result, errors = nil)
+      return result.errors.to_s if result.is_a?(DhanHQ::ErrorObject)
+      return errors.to_s if errors && !errors.empty?
+
+      # `nil` and `false` carry nothing, so say which of the two it was rather than
+      # inventing a cause.
+      result.nil? ? "the API returned no record" : "the API rejected the request"
+    end
+  end
+end

data/lib/dhan_hq.rb

@@ -35,6 +35,11 @@ module DhanHQ
     "base_api" => "BaseAPI",
     "ip_setup" => "IPSetup",
     "json_loader" => "JSONLoader",
+    # Same failure as "ai" above: mcp.rb defines DhanHQ::MCP while Zeitwerk expected
+    # DhanHQ::Mcp, so DhanHQ::MCP::Server raised NameError after a bare `require
+    # "dhan_hq"` — it only worked via exe/dhanhq-mcp and lib/dhan_hq/mcp.rb, which
+    # require_relative the file directly instead of going through the autoloader.
+    "mcp" => "MCP",
     "ws" => "WS"
   )
   LOADER.push_dir(File.join(__dir__, "DhanHQ"), namespace: self)

data/skills/dhanhq-ruby/references/portfolio.md

@@ -70,24 +70,31 @@ position.convert(
 
 ## eDIS Authorization
 
-For selling delivery holdings, authorization is handled via `DhanHQ::Models::EDIS`:
+For selling delivery holdings, authorization is handled via `DhanHQ::Models::Edis`:
 
 ### Step 1: Generate TPIN
 ```ruby
-DhanHQ::Models::EDIS.generate_tpin
+DhanHQ::Models::Edis.generate_tpin
 ```
 
-### Step 2: Open Browser Authorization
+Triggers a TPIN to the user's registered mobile/email. Returns `{status: "accepted"}` — the API responds `202` for this async operation.
+
+### Step 2: Generate and Render the Authorization Form
 ```ruby
-DhanHQ::Models::EDIS.open_browser_for_tpin(
+form = DhanHQ::Models::Edis.generate_form(
   isin: "INE002A01018",
   qty: 5,
-  exchange: "NSE"
+  exchange: "NSE",
+  segment: "EQ"
 )
+# form[:edisFormHtml] is a browser-postable HTML form; render or POST it so the
+# user can complete authorization on Dhan's eDIS page.
 ```
 
-### Step 3: Inquiry eDIS Approval
+### Step 3: Inquire eDIS Approval
 ```ruby
-inquiry = DhanHQ::Models::EDIS.inquiry(isin: "INE002A01018")
-puts "Approved Qty: #{inquiry.aprvd_qty}, Status: #{inquiry.status}"
+status = DhanHQ::Models::Edis.inquire(isin: "INE002A01018") # or isin: "ALL"
+puts "Approved Qty: #{status[:aprvdQty]}, Status: #{status[:status]}"
 ```
+
+`inquire` returns the raw API response (a `HashWithIndifferentAccess`), not a model instance — key names match the API's camelCase (`aprvdQty`, `totalQty`), not the snake_case used elsewhere in this gem.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 3.2.1
+  version: 3.3.0
 platform: ruby
 authors:
 - Shubham Taywade
@@ -229,7 +229,9 @@ files:
 - lib/DhanHQ/auth/token_manager.rb
 - lib/DhanHQ/auth/token_renewal.rb
 - lib/DhanHQ/client.rb
+- lib/DhanHQ/concerns/bang_writes.rb
 - lib/DhanHQ/concerns/order_audit.rb
+- lib/DhanHQ/concerns/tracked_writes.rb
 - lib/DhanHQ/configuration.rb
 - lib/DhanHQ/constants.rb
 - lib/DhanHQ/contracts/alert_order_contract.rb
@@ -266,6 +268,7 @@ files:
 - lib/DhanHQ/core/base_model.rb
 - lib/DhanHQ/core/base_resource.rb
 - lib/DhanHQ/core/error_handler.rb
+- lib/DhanHQ/deprecation.rb
 - lib/DhanHQ/dry_run/ledger.rb
 - lib/DhanHQ/dry_run/simulator.rb
 - lib/DhanHQ/error_object.rb
@@ -391,6 +394,7 @@ files:
 - lib/DhanHQ/utils/network_inspector.rb
 - lib/DhanHQ/version.rb
 - lib/DhanHQ/write_paths.rb
+- lib/DhanHQ/write_result.rb
 - lib/DhanHQ/ws.rb
 - lib/DhanHQ/ws/base_connection.rb
 - lib/DhanHQ/ws/client.rb