DhanHQ 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 474564a108e478d3e2cc7bb0ad2b313a885b265ca3ece5091bd04dc1bb31b014
-  data.tar.gz: ab2a03010eb2ca03f7e6c9a01011b1b4b84f805611f22c55f7c2c07af1a7e063
+  metadata.gz: 065ac08985790dc4172816430025c482f539b506445c84181f69bdb56d30f510
+  data.tar.gz: 8f545f2ac8416dfadfe4fc0a5216b4203d06eaf05e1b1094d14ee571e84de342
 SHA512:
-  metadata.gz: 531c7d4fba8e753c2371569a47562ed32cd026c8a2828e28bb7b617f5f342bec870ace4fac6f95b4e122b360c164c42a65a34a90899e2e100b18e7cc594ffea0
-  data.tar.gz: 82332825d24456beeb67b61836472c05047ff323c3826f2f8324ac06ae036c10e9324788a43e1e7dbdcc74fb60cdbc385aaf373d99d851bb6732c51f6bf7638b
+  metadata.gz: 27d821b96f67997c64f1a523c2a366736dabcea5175e621014e22c9b691f35835f008f3bacaefe6b26229d2de92a78d44719f1b5ebff3e288960f156f7192331
+  data.tar.gz: 76558d36116bbc9c2b024aacc0c6cb1c30640b777cf2cd0832cb6d8da9b142fd6aca350318489a3d13f848136c1089bcd1ef014a2a975c8f66bde1e7c8131d10

data/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+This is a pure-Ruby gem (no Rails, no running servers). Development commands are documented in `CLAUDE.md`.
+
+### Quick reference
+
+| Task | Command |
+|------|---------|
+| Install deps | `bundle install` |
+| Tests | `bundle exec rspec` |
+| Lint | `bundle exec rubocop` |
+| Both | `bundle exec rake` |
+| Single spec | `bundle exec rspec spec/path/to_spec.rb` |
+
+### Non-obvious caveats
+
+- **Bundler 4.x required**: The lockfile was bundled with Bundler 4.0.6. Install with `sudo gem install bundler -v 4.0.6` if missing.
+- **`libyaml-dev` must be installed**: The `psych` gem (transitive dep) needs `yaml.h`. Without `libyaml-dev`, `bundle install` fails on native extension build.
+- **`vendor/bundle` path**: Gems are installed to `./vendor/bundle` via `.bundle/config` to avoid needing root write access to `/var/lib/gems`.
+- **No real API calls in tests**: All HTTP interactions are stubbed with WebMock/VCR. No `DHAN_CLIENT_ID` or `DHAN_ACCESS_TOKEN` secrets are needed to run the test suite.
+- **No services to start**: This is a library gem. There is no web server, database, or background worker. Testing is purely `bundle exec rspec` / `bundle exec rubocop`.

data/CHANGELOG.md

@@ -1,3 +1,77 @@
+## [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
+
+- **Restored the Claude Agent Skill pack to the published gem.** Switching `spec.files` from a reject-list to an allowlist in 3.2.0 stripped 51 MB of junk (a 36 MB core dump and a 17 MB `diagram.html`), but it also dropped `skills/dhanhq-ruby/` — 28 files, 164 KB: `SKILL.md` and its trigger frontmatter, 12 reference guides, 11 examples and 4 helper scripts. That pack is product content, added deliberately in #41. No Ruby code loads it at runtime, so nothing broke and no spec noticed; users installing 3.2.0 simply stopped receiving it. `CODE_OF_CONDUCT.md` and `AGENTS.md` are restored alongside it.
+
+  Unaffected and still shipped throughout: the MCP server (`lib/DhanHQ/mcp/`, `exe/dhanhq-mcp`), the agent tool layer (all 32 tools), the Ruby skills classes (`lib/DhanHQ/skills/`, 11 builtin skills), the risk pipeline and the WebSocket subsystem.
+
+  Gem size: 3.1.0 was 5.9 MB, 3.2.0 was 292 KB, and this is 324 KB. The 20× reduction is real and almost entirely the core dump; the skill pack was collateral.
+- **`DhanHQ::AI` was unreachable on a bare `require "dhan_hq"`.** The Zeitwerk inflector had no `ai → AI` acronym, so it looked for `DhanHQ::Ai` while `ai.rb` defines `DhanHQ::AI`; both spellings raised `NameError`. The documented `DhanHQ::AI::PromptHelpers` and `DhanHQ::AI::ContextBuilder` entry points therefore only worked if something had already loaded the file by hand, which only `mcp/server.rb` did. Found while writing the first specs for that module.
+
+### Added
+
+- **`spec/dhan_hq/gem_packaging_spec.rb`** — pins both ends of what ships, since packaging has now failed in both directions. Asserts the entry point, both executables, RBS signatures, Rails initializer, MCP server, agent tool layer, Ruby skills and the Claude Skill pack are all present; asserts the known junk, any crash dump, the spec suite and development config are all absent; and caps the uncompressed payload at 3 MB so a stray binary fails loudly rather than silently adding megabytes to a release.
+- First specs for `AI::PromptHelpers` (13 examples), covering portfolio summaries, the risk report's P&L arithmetic — summed across every position, counted only for open ones — and order confirmation rendering. Built on real model instances rather than doubles, because `BaseModel` defines attribute readers per instance and `instance_double` cannot verify them.
+- Specs for the lazily-built connection (not opened on construction, memoised, rebuilt on a base-URL change) and for retry exhaustion (transport errors translated, SDK errors re-raised unchanged, reads still retried).
+
+### Changed
+
+- **`Client#with_transient_retry` no longer duplicates its retry branch.** It had two rescue clauses running near-identical backoff-log-sleep-retry logic, differing only in what they raised once retries were spent. Collapsed into one clause, with an `exhausted_error` helper naming the difference: Faraday's transport errors are translated to `DhanHQ::NetworkError` (they are not part of this gem's hierarchy, so a caller rescuing `DhanHQ::Error` would otherwise miss them), while the gem's own errors are re-raised unchanged. Clears the `Lint/DuplicateBranch` pressure on this method.
+- **`Client#initialize` no longer opens a connection.** It now establishes state and checks its one invariant; the Faraday connection is built on first use of `#connection` and rebuilt when the configured base URL changes. Behaviour is unchanged for callers — `#connection` is still public and still reflects a sandbox toggle mid-process — but constructing a client does no network setup.
+- **`Naming/PredicateMethod` is now scoped by method name instead of by file.** Seven file-level exclusions replaced with `AllowedMethods: [cancel, modify, destroy]` plus `AllowBangMethods: true`.
+
+  These are commands that report whether they succeeded, not predicates — `cancel?` would read as "should I cancel?", which is worse than the name it replaces, so adding `?` aliases would have been the wrong fix. The unambiguous-failure path for them is the bang variant (`cancel!`, `modify!`). Scoping by name rather than by file also means a genuinely mis-named predicate elsewhere in those same files is still caught, and it surfaced a now-redundant inline `rubocop:disable` in `risk/pipeline.rb`.
+- `AI::PromptHelpers.portfolio_summary` computed the open-position set twice (`count(&:open?)` then `select(&:open?)`); it now derives it once. Both it and `.risk_report` wrap their collections in `Array()`, so a nil from a failed fetch renders an empty section instead of raising from inside a prompt helper — `funds` was already guarded, the collections were not.
+
 ## [3.2.0] - 2026-07-25
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

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/ai/prompt_helpers.rb

@@ -41,14 +41,20 @@ module DhanHQ
       # @param funds [DhanHQ::Models::Funds] Funds data
       # @return [String] Portfolio summary
       def self.portfolio_summary(holdings:, positions:, funds:)
+        # Array() so a missing collection renders as an empty section instead of
+        # raising. `funds` was already guarded; these two were not, and a prompt
+        # helper failing hard on an empty portfolio is the wrong trade.
+        all_holdings = Array(holdings)
+        open_positions = Array(positions).select(&:open?)
+
         lines = ["=== Portfolio Summary ==="]
         lines << "Funds: #{funds.to_prompt}" if funds
         lines << ""
-        lines << "Holdings (#{holdings.size}):"
-        holdings.each { |h| lines << "  #{h.to_prompt}" }
+        lines << "Holdings (#{all_holdings.size}):"
+        all_holdings.each { |holding| lines << "  #{holding.to_prompt}" }
         lines << ""
-        lines << "Open Positions (#{positions.count(&:open?)}):"
-        positions.select(&:open?).each { |p| lines << "  #{p.to_prompt}" }
+        lines << "Open Positions (#{open_positions.size}):"
+        open_positions.each { |position| lines << "  #{position.to_prompt}" }
         lines.join("\n")
       end
 
@@ -95,13 +101,17 @@ module DhanHQ
       # @param risk_params [Hash] Risk parameters
       # @return [String] Risk report
       def self.risk_report(positions:, risk_params: {})
+        # P&L is summed across every position; only the count is restricted to open
+        # ones, since a closed position still contributed realised P&L today.
+        all_positions = Array(positions)
+
         lines = ["=== Risk Report ==="]
-        total_unrealized = positions.sum { |p| p.unrealized_profit.to_f }
-        total_realized = positions.sum { |p| p.realized_profit.to_f }
+        total_unrealized = all_positions.sum { |position| position.unrealized_profit.to_f }
+        total_realized = all_positions.sum { |position| position.realized_profit.to_f }
 
         lines << "Total Unrealized P&L: ₹#{total_unrealized.round(2)}"
         lines << "Total Realized P&L: ₹#{total_realized.round(2)}"
-        lines << "Open Positions: #{positions.count(&:open?)}"
+        lines << "Open Positions: #{all_positions.count(&:open?)}"
 
         lines << "Max Drawdown: #{risk_params[:max_drawdown]}%" if risk_params[:max_drawdown]
 

data/lib/DhanHQ/client.rb

@@ -25,31 +25,57 @@ module DhanHQ
     include DhanHQ::RequestHelper
     include DhanHQ::ResponseHelper
 
-    # The Faraday connection object used for HTTP requests.
-    #
-    # @return [Faraday::Connection] The connection instance used for API requests.
-    attr_reader :connection
+    # Transient failures raised by this gem, worth retrying as-is.
+    RETRYABLE_SDK_ERRORS = [
+      DhanHQ::RateLimitError,
+      DhanHQ::InternalServerError,
+      DhanHQ::NetworkError
+    ].freeze
+    private_constant :RETRYABLE_SDK_ERRORS
+
+    # Transport failures raised by Faraday. Also worth retrying, but they are not part
+    # of this gem's error hierarchy, so a caller rescuing DhanHQ::Error would miss
+    # them — they are translated on the way out. See {#exhausted_error}.
+    RETRYABLE_TRANSPORT_ERRORS = [
+      Faraday::TimeoutError,
+      Faraday::ConnectionFailed
+    ].freeze
+    private_constant :RETRYABLE_TRANSPORT_ERRORS
 
     attr_reader :token_manager
 
-    # Initializes a new DhanHQ Client instance with a Faraday connection.
+    # Initializes a new DhanHQ Client.
+    #
+    # Establishes state and checks its one invariant; the HTTP connection is opened
+    # lazily on first use, so constructing a client does no network setup.
     #
     # @example Create a new client:
     #   client = DhanHQ::Client.new(api_type: :order_api)
     #
     # @param api_type [Symbol] Type of API (`:order_api`, `:data_api`, `:non_trading_api`)
     # @return [DhanHQ::Client] A new client instance.
-    # @raise [DhanHQ::Error] If configuration is invalid or rate limiter initialization fails
+    # @raise [DhanHQ::Error] If the rate limiter cannot be resolved for this API type.
     def initialize(api_type:)
       DhanHQ.ensure_configuration!
-      # Use shared rate limiter instance per API type to ensure proper coordination
+      # Shared per API type, so separate clients coordinate against one limit.
       @rate_limiter = RateLimiter.for(api_type)
 
       raise DhanHQ::Error, "RateLimiter initialization failed" unless @rate_limiter
+    end
+
+    # The Faraday connection used for HTTP requests.
+    #
+    # Built on first use and rebuilt whenever the configured base URL changes — which
+    # happens when sandbox mode is toggled, or when a token endpoint hands back a
+    # different host mid-process.
+    #
+    # @return [Faraday::Connection]
+    def connection
+      current_url = DhanHQ.configuration.base_url
+      return @connection if @connection && @last_base_url == current_url
 
-      # Store initial URL to detect changes
-      @last_base_url = DhanHQ.configuration.base_url
-      @connection = build_connection(@last_base_url)
+      @last_base_url = current_url
+      @connection = build_connection(current_url)
     end
 
     # Sends an HTTP request to the API with automatic retry for transient errors.
@@ -66,7 +92,6 @@ module DhanHQ
 
       @token_manager&.ensure_valid_token!
       @rate_limiter.throttle!
-      refresh_connection!
 
       # A non-idempotent write is not safely retryable: the API has no idempotency
       # key, so a request that timed out may already have reached the exchange.
@@ -99,27 +124,13 @@ module DhanHQ
       attempt = 0
       begin
         yield
-      rescue DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError => e
-        attempt += 1
-        raise if attempt > retries
-
-        backoff = calculate_backoff(attempt)
-        DhanHQ.logger&.warn(
-          "[DhanHQ::Client] Transient error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
-        )
-        sleep(backoff)
-        retry
-      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      rescue *RETRYABLE_SDK_ERRORS, *RETRYABLE_TRANSPORT_ERRORS => e
         attempt += 1
-        if attempt > retries
-          raise DhanHQ::NetworkError, "Request failed: #{e.message}" if retries.zero?
-
-          raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}"
-        end
+        raise exhausted_error(e, retries) if attempt > retries
 
         backoff = calculate_backoff(attempt)
         DhanHQ.logger&.warn(
-          "[DhanHQ::Client] Network error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
+          "[DhanHQ::Client] Transient failure (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
         )
         sleep(backoff)
         retry
@@ -253,12 +264,20 @@ module DhanHQ
       out
     end
 
-    def refresh_connection!
-      current_url = DhanHQ.configuration.base_url
-      return if @last_base_url == current_url
-
-      @last_base_url = current_url
-      @connection = build_connection(current_url)
+    # The exception to raise once the retries are spent.
+    #
+    # Faraday's transport errors are translated to {DhanHQ::NetworkError}, so a caller
+    # rescuing DhanHQ::Error sees every failure this client can produce. This gem's own
+    # errors already belong to that hierarchy and are re-raised unchanged.
+    #
+    # @param error [StandardError] The failure that exhausted the retries.
+    # @param retries [Integer] How many retries were allowed.
+    # @return [StandardError] The exception to raise.
+    def exhausted_error(error, retries)
+      return error unless RETRYABLE_TRANSPORT_ERRORS.any? { |klass| error.is_a?(klass) }
+
+      attempts = retries.zero? ? "" : " after #{retries} retries"
+      DhanHQ::NetworkError.new("Request failed#{attempts}: #{error.message}")
     end
 
     def build_connection(url)