DhanHQ 2.1.3 → 2.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ee56ccabd71b9f769e99d6470cf32309c4f6fa17eec5de17417b1c153ee9293
-  data.tar.gz: 000fcabd622e0e690f6c65bf03665b8e4b3dfc23572534d29101fca0576757be
+  metadata.gz: 5b28412f443ad7ef0da9f10e99cee98dff8194b0d9da3c9d828dba28e3443fce
+  data.tar.gz: 96c1411c9e3c579f35637bfb37f9644348e0d75f5fbe9a502da59789da4607ba
 SHA512:
-  metadata.gz: 6aeecd46b742a5cbdf74ffb4e38086be502385fda9e18bee4b6413a488b005b2a713dd089cd2d83c6628096d084d063bb6da468292b785d08f968fc9336838ac
-  data.tar.gz: b4fe91bca2051073b297693d1ea2789911b8b50b3a948ccf96cc7b0647a1fe824020f39ca0cbfebf53946b453253d8348df7d673eb199068d24d444453191b8d
+  metadata.gz: 313c052fc68d670ce53005b091f70280617c0414a9fa1f6222d0f641b3181660bcdbf92eae5f6ece36fa500f1a554faee024114b2e132c1b2e3602b384a67cc3
+  data.tar.gz: e20baecdc074b57d78024bf5004a8808eb5397d3d1edb5743178ad50aa369e15250219c1f52384e1f00619fc8edd56bc97501ac8df375c95c7e61ca08dca96d9

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 plugins:
   - rubocop-rspec
   - rubocop-performance

data/.rubocop_todo.yml

@@ -0,0 +1,185 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit 999`
+# on 2025-10-12 11:03:03 UTC using RuboCop version 1.80.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Exclude:
+    - 'lib/DhanHQ/ws/decoder.rb'
+
+# Offense count: 2
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'bin/ta_strategy.rb'
+    - 'lib/dhanhq/analysis/helpers/bias_aggregator.rb'
+
+# Offense count: 3
+# Configuration parameters: AllowComments, AllowNil.
+Lint/SuppressedException:
+  Exclude:
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/registry.rb'
+
+# Offense count: 42
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'bin/ta_strategy.rb'
+    - 'bin/ws_feed_test.rb'
+    - 'lib/DhanHQ/helpers/response_helper.rb'
+    - 'lib/DhanHQ/models/order.rb'
+    - 'lib/DhanHQ/rate_limiter.rb'
+    - 'lib/DhanHQ/ws/client.rb'
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/decoder.rb'
+    - 'lib/DhanHQ/ws/orders/connection.rb'
+    - 'lib/DhanHQ/ws/websocket_packet_parser.rb'
+    - 'lib/dhan_hq.rb'
+    - 'lib/dhanhq/analysis/helpers/bias_aggregator.rb'
+    - 'lib/dhanhq/analysis/multi_timeframe_analyzer.rb'
+    - 'lib/dhanhq/analysis/options_buying_advisor.rb'
+    - 'lib/ta/candles.rb'
+    - 'lib/ta/fetcher.rb'
+    - 'lib/ta/indicators.rb'
+    - 'lib/ta/technical_analysis.rb'
+
+# Offense count: 1
+# Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Exclude:
+    - 'lib/DhanHQ/ws/connection.rb'
+
+# Offense count: 8
+# Configuration parameters: CountComments, Max, CountAsOne.
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/DhanHQ/core/base_model.rb'
+    - 'lib/DhanHQ/models/order.rb'
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/orders/connection.rb'
+    - 'lib/DhanHQ/ws/websocket_packet_parser.rb'
+    - 'lib/dhanhq/analysis/multi_timeframe_analyzer.rb'
+    - 'lib/dhanhq/analysis/options_buying_advisor.rb'
+    - 'lib/ta/technical_analysis.rb'
+
+# Offense count: 25
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'bin/ta_strategy.rb'
+    - 'bin/ws_feed_test.rb'
+    - 'lib/DhanHQ/helpers/response_helper.rb'
+    - 'lib/DhanHQ/models/order.rb'
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/decoder.rb'
+    - 'lib/DhanHQ/ws/orders/connection.rb'
+    - 'lib/DhanHQ/ws/segments.rb'
+    - 'lib/DhanHQ/ws/websocket_packet_parser.rb'
+    - 'lib/dhanhq/analysis/helpers/bias_aggregator.rb'
+    - 'lib/dhanhq/analysis/multi_timeframe_analyzer.rb'
+    - 'lib/dhanhq/analysis/options_buying_advisor.rb'
+    - 'lib/ta/candles.rb'
+    - 'lib/ta/indicators.rb'
+    - 'lib/ta/technical_analysis.rb'
+
+# Offense count: 52
+# Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Exclude:
+    - 'bin/ta_strategy.rb'
+    - 'bin/ws_feed_test.rb'
+    - 'lib/DhanHQ/core/base_model.rb'
+    - 'lib/DhanHQ/helpers/response_helper.rb'
+    - 'lib/DhanHQ/models/holding.rb'
+    - 'lib/DhanHQ/models/instrument.rb'
+    - 'lib/DhanHQ/models/ledger_entry.rb'
+    - 'lib/DhanHQ/models/order.rb'
+    - 'lib/DhanHQ/rate_limiter.rb'
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/decoder.rb'
+    - 'lib/DhanHQ/ws/orders/connection.rb'
+    - 'lib/DhanHQ/ws/segments.rb'
+    - 'lib/DhanHQ/ws/singleton_lock.rb'
+    - 'lib/DhanHQ/ws/websocket_packet_parser.rb'
+    - 'lib/dhanhq/analysis/helpers/bias_aggregator.rb'
+    - 'lib/dhanhq/analysis/multi_timeframe_analyzer.rb'
+    - 'lib/dhanhq/analysis/options_buying_advisor.rb'
+    - 'lib/ta/candles.rb'
+    - 'lib/ta/fetcher.rb'
+    - 'lib/ta/indicators.rb'
+    - 'lib/ta/technical_analysis.rb'
+
+# Offense count: 3
+# Configuration parameters: CountComments, Max, CountAsOne.
+Metrics/ModuleLength:
+  Exclude:
+    - 'bin/ta_strategy.rb'
+    - 'lib/DhanHQ/constants.rb'
+    - 'lib/ta/indicators.rb'
+
+# Offense count: 1
+# Configuration parameters: Max, CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/ta/technical_analysis.rb'
+
+# Offense count: 21
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'bin/ta_strategy.rb'
+    - 'bin/ws_feed_test.rb'
+    - 'lib/DhanHQ/helpers/response_helper.rb'
+    - 'lib/DhanHQ/models/order.rb'
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/decoder.rb'
+    - 'lib/DhanHQ/ws/orders/connection.rb'
+    - 'lib/dhanhq/analysis/helpers/bias_aggregator.rb'
+    - 'lib/dhanhq/analysis/multi_timeframe_analyzer.rb'
+    - 'lib/dhanhq/analysis/options_buying_advisor.rb'
+    - 'lib/ta/candles.rb'
+    - 'lib/ta/indicators.rb'
+    - 'lib/ta/technical_analysis.rb'
+
+# Offense count: 1
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/DhanHQ/ws/connection.rb'
+
+# Offense count: 7
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/DhanHQ/models/forever_order.rb'
+    - 'lib/DhanHQ/models/order.rb'
+    - 'lib/DhanHQ/models/super_order.rb'
+    - 'lib/DhanHQ/ws/singleton_lock.rb'
+
+# Offense count: 5
+# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
+# SupportedStyles: snake_case, normalcase, non_integer
+# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
+Naming/VariableNumber:
+  Exclude:
+    - 'lib/DhanHQ/ws/connection.rb'
+    - 'lib/DhanHQ/ws/orders/connection.rb'
+
+# Offense count: 3
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'lib/dhanhq/analysis/multi_timeframe_analyzer.rb'
+    - 'lib/ta/fetcher.rb'

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+### Changed
+- Align Super Order documentation across README, README1, and GUIDE with the latest API contract (place, modify, cancel, list).
+- Normalise remaining documentation examples to snake_case, including order update WebSocket callbacks and kill switch response guidance.
+
+## [2.1.5] - 2025-01-27
+
+### ⚠️ BREAKING CHANGES
+- **Changed require statement**: `require 'DhanHQ'` → `require 'dhan_hq'`
+  - This affects all Ruby files that require the gem
+  - Update all `require 'DhanHQ'` statements to `require 'dhan_hq'` in your codebase
+  - The gem name remains `DhanHQ` in your Gemfile, only the require statement changes
+
+### Added
+- **OptionChain validation**: Added proper parameter validation for `OptionChain.fetch` and `OptionChain.fetch_expiry_list` methods
+  - `OptionChain.fetch` requires `underlying_scrip`, `underlying_seg`, and `expiry` parameters
+  - `OptionChain.fetch_expiry_list` requires only `underlying_scrip` and `underlying_seg` parameters
+  - Validates exchange segments against `%w[IDX_I NSE_FNO BSE_FNO MCX_FO]`
+  - Validates expiry format as `YYYY-MM-DD` and ensures it's a valid date
+
+### Fixed
+- **RuboCop compliance**: Fixed all RuboCop offenses (179 → 0 offenses)
+- **Documentation**: Updated all documentation examples to use `require 'dhan_hq'`
+- **Documentation**: Correct Super Order examples to use snake_case parameters for `DhanHQ::Models` helpers
+- **Documentation**: Normalise Super Order path placeholders and response fields to snake_case for consistency
+- **Documentation**: Clarified that model helpers auto-inject `dhan_client_id`, removing the need to add it manually in Ruby payloads
+- **Code quality**: Added comprehensive validation tests for OptionChain methods
+
+### Changed
+- **File structure**: Renamed main library file from `lib/DhanHQ.rb` to `lib/dhan_hq.rb` for better Ruby conventions
+- **Require paths**: Updated all internal require statements to use snake_case naming
+
 ## [2.1.0] - 2025-09-20
 
 - Add REST coverage for EDIS (`/edis/form`, `/edis/bulkform`, `/edis/tpin`, `/edis/inquire/{isin}`) and the account kill-switch endpoint.

data/GUIDE.md

@@ -32,7 +32,7 @@ bundle install
 Bootstrap from environment variables:
 
 ```ruby
-require 'DhanHQ'
+require 'dhan_hq'
 
 DhanHQ.configure_with_env
 DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
@@ -156,9 +156,9 @@ puts order.order_status  # => "TRADED" / "PENDING" / ...
 
 `Order#modify` merges the existing attributes with the supplied overrides and validates against `ModifyOrderContract`.
 
-- Required: the instance must have an `order_id` and `dhan_client_id`.
+- Required: the instance must have an `order_id`; the model reuses the saved `dhan_client_id` when building the payload.
 - At least one of `order_type`, `quantity`, `price`, `trigger_price`, `disclosed_quantity`, `validity` must change.
-- Payload is camelised automatically before hitting `/v2/orders/{orderId}`.
+- Payload is camelised automatically before hitting `/v2/orders/{order_id}`.
 
 ```ruby
 order.modify(price: 154.2, trigger_price: 149.5)
@@ -208,42 +208,174 @@ DhanHQ::Models::Order.resource.slicing(payload)
 
 ### Super Orders
 
-`DhanHQ::Models::SuperOrder` wraps `/v2/super/orders`.
+`DhanHQ::Models::SuperOrder` wraps the `/v2/super/orders` family. A super order combines entry, target, and stop-loss legs into one atomic instruction and supports an optional trailing jump so risk is managed server-side immediately after entry.
 
-```ruby
-legs = {
-  transactionType: "BUY",
-  exchangeSegment: "NSE_FNO",
-  productType: "CO",
-  orderType: "LIMIT",
-  validity: "DAY",
-  securityId: "43492",
-  quantity: 50,
-  price: 100.0,
-  stopLossPrice: 95.0,
-  targetPrice: 110.0
+#### Endpoints
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `POST` | `/super/orders` | Create a new super order |
+| `PUT` | `/super/orders/{order_id}` | Modify a pending super order |
+| `DELETE` | `/super/orders/{order_id}/{order_leg}` | Cancel a pending super order leg |
+| `GET` | `/super/orders` | Retrieve the list of all super orders |
+
+#### Place Super Order
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking these APIs.
+
+```bash
+curl --request POST \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+Request body:
+
+```json
+{
+  "dhan_client_id": "1000000003",
+  "correlation_id": "123abc678",
+  "transaction_type": "BUY",
+  "exchange_segment": "NSE_EQ",
+  "product_type": "CNC",
+  "order_type": "LIMIT",
+  "security_id": "11536",
+  "quantity": 5,
+  "price": 1500,
+  "target_price": 1600,
+  "stop_loss_price": 1400,
+  "trailing_jump": 10
+}
+```
+
+Key parameters:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `dhan_client_id` | string *(required)* | User specific identifier generated by Dhan. Automatically merged when you call through the Ruby model helpers. |
+| `correlation_id` | string | Optional caller supplied correlation id. |
+| `transaction_type` | enum string *(required)* | `BUY` or `SELL`. |
+| `exchange_segment` | enum string *(required)* | Exchange segment. |
+| `product_type` | enum string *(required)* | `CNC`, `INTRADAY`, `MARGIN`, or `MTF`. |
+| `order_type` | enum string *(required)* | `LIMIT` or `MARKET`. |
+| `security_id` | string *(required)* | Exchange security identifier. |
+| `quantity` | integer *(required)* | Entry quantity. |
+| `price` | float *(required)* | Entry price. |
+| `target_price` | float *(required)* | Target price for the super order. |
+| `stop_loss_price` | float *(required)* | Stop-loss price for the super order. |
+| `trailing_jump` | float *(required)* | Trailing jump size. |
+
+> 🐍 Pass snake_case keys when invoking `DhanHQ::Models::SuperOrder.create`—the client camelizes internally before calling the REST API and injects your configured `dhan_client_id`, so the key is optional in Ruby payloads.
+
+Response:
+
+```json
+{
+  "order_id": "112111182198",
+  "order_status": "PENDING"
 }
+```
 
-super_order = DhanHQ::Models::SuperOrder.create(legs)
-super_order.modify(trailingJump: 2.5)
-super_order.cancel("ENTRY_LEG")
+#### Modify Super Order
+
+Modify while the order is `PENDING` or `PART_TRADED`. Entry leg updates adjust the entire super order until the entry trades; afterwards only target and stop-loss legs (price, trailing) remain editable.
+
+```bash
+curl --request PUT \
+  --url https://api.dhan.co/v2/super/orders/{order_id} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+Example payload:
+
+```json
+{
+  "dhan_client_id": "1000000009",
+  "order_id": "112111182045",
+  "order_type": "LIMIT",
+  "leg_name": "ENTRY_LEG",
+  "quantity": 40,
+  "price": 1300,
+  "target_price": 1450,
+  "stop_loss_price": 1350,
+  "trailing_jump": 20
+}
+```
+
+Conditional fields:
+
+| Field | Required when | Notes |
+| --- | --- | --- |
+| `order_type` | Updating `ENTRY_LEG` | `LIMIT` or `MARKET`. |
+| `quantity` | Updating `ENTRY_LEG` | Adjusts entry quantity. |
+| `price` | Updating `ENTRY_LEG` | Adjusts entry price. |
+| `target_price` | Updating `ENTRY_LEG` or `TARGET_LEG` | Adjusts target price. |
+| `stop_loss_price` | Updating `ENTRY_LEG` or `STOP_LOSS_LEG` | Adjusts stop-loss price. |
+| `trailing_jump` | Updating `ENTRY_LEG` or `STOP_LOSS_LEG` | Pass `0` or omit to cancel trailing. |
+
+Response:
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "TRANSIT"
+}
 ```
 
+#### Cancel Super Order
+
+```bash
+curl --request DELETE \
+  --url https://api.dhan.co/v2/super/orders/{order_id}/{order_leg} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+Path parameters:
+
+| Field | Description | Example |
+| --- | --- | --- |
+| `order_id` | Super order identifier. | `11211182198` |
+| `order_leg` | Leg to cancel (`ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`). | `ENTRY_LEG` |
+
+Response:
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "CANCELLED"
+}
+```
+
+#### Super Order List
+
+```bash
+curl --request GET \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+The response returns one object per super order with nested `leg_details`. Key attributes include `order_status`, `filled_qty`, `remaining_quantity`, `average_traded_price`, and leg-level trailing configuration. `CLOSED` indicates the entry plus either target or stop-loss filled the entire quantity; `TRIGGERED` surfaces on the target or stop-loss leg that fired.
+
 ### Forever Orders (GTT)
 
 `DhanHQ::Models::ForeverOrder` maps to `/v2/forever/orders`.
 
 ```ruby
 params = {
-  dhanClientId: "123456",
-  transactionType: "SELL",
-  exchangeSegment: "NSE_EQ",
-  productType: "CNC",
-  orderType: "LIMIT",
+  transaction_type: "SELL",
+  exchange_segment: "NSE_EQ",
+  product_type: "CNC",
+  order_type: "LIMIT",
   validity: "DAY",
-  securityId: "1333",
+  security_id: "1333",
   price: 200.0,
-  triggerPrice: 198.0
+  trigger_price: 198.0
 }
 
 forever_order = DhanHQ::Models::ForeverOrder.create(params)
@@ -251,6 +383,8 @@ forever_order.modify(price: 205.0)
 forever_order.cancel
 ```
 
+> 🪄 Model helpers merge the configured `dhan_client_id` automatically, so you can omit it when constructing Ruby hashes like the example above.
+
 The forever order helpers accept snake_case parameters and camelize them internally; only the low-level resource requires raw API casing.
 
 ---
@@ -268,7 +402,6 @@ Convert an intraday position to delivery (or vice versa):
 
 ```ruby
 convert_payload = {
-  dhan_client_id: "123456",
   security_id: "1333",
   from_product_type: "INTRADAY",
   to_product_type: "CNC",
@@ -281,6 +414,8 @@ response = DhanHQ::Models::Position.convert(convert_payload)
 raise response.errors.to_s if response.is_a?(DhanHQ::ErrorObject)
 ```
 
+> 🪄 No need to merge `dhan_client_id`; the helper adds it from your configuration before calling `/v2/positions/convert`.
+
 The conversion helper validates the payload with `PositionConversionContract`; missing or invalid fields raise `DhanHQ::Error` before the request is sent.
 
 ### Holdings
@@ -379,7 +514,6 @@ The model filters strikes where both CE and PE have zero `last_price`, keeping t
 
 ```ruby
 params = {
-  dhan_client_id: "123456",
   exchange_segment: "NSE_EQ",
   transaction_type: "BUY",
   quantity: 10,
@@ -392,6 +526,8 @@ margin = DhanHQ::Models::Margin.calculate(params)
 puts margin.total_margin
 ```
 
+> 🪄 The margin helper appends `dhan_client_id` from your credentials before calling `/v2/margincalculator`.
+
 If a required field is missing (for example `transaction_type`), the contract raises `DhanHQ::Error` before any API call is issued.
 
 ### REST Market Feed (Batch LTP/OHLC/Quote)
@@ -473,14 +609,20 @@ All helpers accept snake_case keys; the client camelizes them before calling `/v
 ### Kill Switch
 
 ```ruby
-DhanHQ::Models::KillSwitch.activate    # => {"killSwitchStatus"=>"ACTIVATE"}
-DhanHQ::Models::KillSwitch.deactivate  # => {"killSwitchStatus"=>"DEACTIVATE"}
+activate_payload   = DhanHQ::Models::KillSwitch.activate
+deactivate_payload = DhanHQ::Models::KillSwitch.deactivate
+
+DhanHQ::Models::KillSwitch.snake_case(activate_payload)
+# => { kill_switch_status: "ACTIVATE" }
+
+DhanHQ::Models::KillSwitch.snake_case(deactivate_payload)
+# => { kill_switch_status: "DEACTIVATE" }
 
 # Explicit status update
 DhanHQ::Models::KillSwitch.update("ACTIVATE")
 ```
 
-Only `"ACTIVATE"` and `"DEACTIVATE"` are accepted—any other value raises `DhanHQ::Error`.
+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.
 
 ---