fix: correct documentation examples and align config template with code defaults (#824)

userFRM · claude · web-flow · commit 6ed69ce1b091 · 2026-06-16T15:17:34.000Z
Several documented examples used call shapes that do not compile or run against the real surface: the Python OHLC example passed `interval` positionally though it is keyword-only, the concurrent-requests article reached for a `historical` view that the async client does not expose, the bulk-backfill Rust sample treated `historical` as a field rather than a method, and the CLI EOD-Greeks example listed positional arguments out of registry order. Each is fixed to the verified signature.

The shipped `config.default.toml` wrote three tuning values that overrode the production defaults the moment a client copied the template, because the loader only backfills absent keys: read timeout, client ping interval, and the initial reconnect wait now match `DirectConfig::production()` exactly (3000 ms, 250 ms, 250 ms). A new `config_default_toml_matches_production_defaults` test pins every parsed value to the in-code defaults so the template can never silently drift again.

Endpoint counts in the top-level and per-SDK READMEs are recounted from `endpoint_surface.toml`: 65 typed endpoints total (16 stock, 36 option, 9 index, 3 calendar, 1 interest rate). The unsourceable Greeks count is replaced with an accurate first- through third-order phrasing, the TypeScript "method on Client" sentence is corrected to `client.historical`, and the crate streaming example uses the real `.streaming.hosts` field.

The Python streaming docs gain a feed-health snippet using the observability getters, and the OHLC interval examples standardize on the duration-string form across Python and TypeScript.

The TypeScript doc-example extractor only matched column-0 fences, so it never saw the fenced blocks inside JSDoc comments and validated zero examples. It now strips the JSDoc gutter, scans the README as well, groups narrative blocks into compilable units, and type-checks each through `tsc --noEmit`.

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # ThetaDataDx
 
-High-performance market-data SDKs for [ThetaData](https://thetadata.us), in **Python, TypeScript, C++, and Rust** — one Rust engine under all four. Pull US stock, option, index, and rate data three ways: point-in-time **history**, real-time **streaming**, and whole-universe **flat files**, all from a single authenticated client. Connects straight to ThetaData — no Java terminal, no JVM.
+High-performance market-data SDKs for [ThetaData](https://thetadata.us), in **Python, TypeScript, C++, and Rust** — one Rust engine under all four. Pull US stock, option, index, and rate data three ways: point-in-time **history**, real-time **streaming**, and whole-universe **flat files**, all from a single authenticated client. Connects straight to ThetaData — nothing to install and run locally.
 
 [![Rust CI](https://github.com/userFRM/ThetaDataDx/actions/workflows/ci.yml/badge.svg)](https://github.com/userFRM/ThetaDataDx/actions/workflows/ci.yml)
 [![Python SDK](https://github.com/userFRM/ThetaDataDx/actions/workflows/python.yml/badge.svg)](https://github.com/userFRM/ThetaDataDx/actions/workflows/python.yml)
@@ -25,10 +25,10 @@ High-performance market-data SDKs for [ThetaData](https://thetadata.us), in **Py
 
 ## Features
 
-- **Complete coverage** — stocks, options, indices, and rates across 61 typed endpoints.
+- **Complete coverage** — stocks, options, indices, and rates across 65 typed endpoints.
 - **Three access modes, one client** — point-in-time history, real-time streaming, and bulk flat-file downloads.
 - **DataFrames built in** — every result chains straight to Polars, pandas, or Arrow over a zero-copy boundary.
-- **Greeks without a round-trip** — 23 Black-Scholes Greeks and an implied-volatility solver, computed locally.
+- **Greeks without a round-trip** — first- through third-order Black-Scholes Greeks and an implied-volatility solver, computed locally.
 - **The same surface in every language** — identical methods and identical typed errors, Python through Rust.
 - **No terminal to run** — a direct connection to ThetaData; nothing to install and babysit locally.
 
@@ -224,13 +224,13 @@ with client.streaming(on_event) as session:
 
 ## Endpoint coverage
 
-61 typed endpoints across stocks, options, indices, the market calendar, and
+65 typed endpoints across stocks, options, indices, the market calendar, and
 interest rates, plus real-time streaming and a local Greeks calculator.
 
 | Category | Endpoints | Examples |
 |---|---|---|
-| Stock | 14 | EOD, OHLC, trades, quotes, snapshots, at-time |
-| Option | 34 | Every stock surface plus five Greeks tiers, open interest, contract lists |
+| Stock | 16 | EOD, OHLC, trades, quotes, snapshots, at-time |
+| Option | 36 | Every stock surface plus five Greeks tiers, open interest, contract lists |
 | Index | 9 | EOD, OHLC, price, snapshots |
 | Calendar | 3 | Market open/close, holidays, early closes |
 | Interest rate | 1 | EOD rate history |
diff --git a/crates/thetadatadx/README.md b/crates/thetadatadx/README.md
@@ -1,6 +1,6 @@
 # thetadatadx
 
-The Rust SDK for [ThetaData](https://thetadata.us) market data. Pull US stock, option, index, and rate data three ways — point-in-time **history**, real-time **streaming**, and whole-universe **flat files** — from one async client. Connects straight to ThetaData; no Java terminal, no JVM, no local proxy.
+The Rust SDK for [ThetaData](https://thetadata.us) market data. Pull US stock, option, index, and rate data three ways — point-in-time **history**, real-time **streaming**, and whole-universe **flat files** — from one async client. Connects straight to ThetaData; nothing to install and run locally, no local proxy.
 
 [![Crates.io](https://img.shields.io/crates/v/thetadatadx.svg?logo=rust)](https://crates.io/crates/thetadatadx)
 [![docs.rs](https://img.shields.io/docsrs/thetadatadx?logo=docsdotrs)](https://docs.rs/thetadatadx)
@@ -12,9 +12,9 @@ The Rust SDK for [ThetaData](https://thetadata.us) market data. Pull US stock, o
 
 ## Features
 
-- **Complete coverage** — stocks, options, indices, and rates across 61 typed endpoints.
+- **Complete coverage** — stocks, options, indices, and rates across 65 typed endpoints.
 - **Three access modes, one client** — point-in-time history, real-time streaming, and bulk flat-file downloads.
-- **Greeks without a round-trip** — 23 Black-Scholes Greeks and an implied-volatility solver, computed locally.
+- **Greeks without a round-trip** — first- through third-order Black-Scholes Greeks and an implied-volatility solver, computed locally.
 - **Buffer or stream** — every history builder yields a `Vec<Tick>` on `.await`, or chunk-by-chunk via `.stream(handler)`.
 - **Typed errors** — one `Error` enum across every transport, plus a dedicated `FpssError` for the streaming path.
 - **DataFrames on demand** — opt into the `polars` / `arrow` features for a zero-copy conversion off any result.
@@ -64,7 +64,7 @@ async fn main() -> Result<(), thetadatadx::Error> {
 }
 ```
 
-61 typed endpoints span stocks, options, indices, the market calendar, and interest rates. Each builder accepts `.await` for a buffered `Vec<Tick>`, or `.stream(handler)` for chunk-by-chunk delivery — the right choice for multi-day backfills, where it holds peak memory flat instead of materialising the whole response.
+65 typed endpoints span stocks, options, indices, the market calendar, and interest rates. Each builder accepts `.await` for a buffered `Vec<Tick>`, or `.stream(handler)` for chunk-by-chunk delivery — the right choice for multi-day backfills, where it holds peak memory flat instead of materialising the whole response.
 
 ## Streaming
 
@@ -148,7 +148,7 @@ use thetadatadx::fpss::protocol::Contract;
 use thetadatadx::fpss::{StreamingClient, StreamEvent};
 
 let creds = Credentials::from_file("creds.txt")?;
-let hosts = DirectConfig::production().fpss.hosts;
+let hosts = DirectConfig::production().streaming.hosts;
 let client = StreamingClient::builder(&creds, &hosts).ring_size(8192).build()?;
 
 client.subscribe(Contract::stock("AAPL").quote())?;
@@ -179,7 +179,7 @@ let path = thetadatadx::flatfile_request(
 
 ## Greeks calculator
 
-A full Black-Scholes calculator — 23 Greeks plus an implied-volatility solver — runs locally, no request required.
+A full Black-Scholes calculator — first- through third-order Greeks plus an implied-volatility solver — runs locally, no request required.
 
 ## DataFrames
 
diff --git a/crates/thetadatadx/config.default.toml b/crates/thetadatadx/config.default.toml
@@ -35,15 +35,20 @@ hosts = [
 # Connection timeout per server attempt (ms)
 connect_timeout = 2000
 
-# Read timeout — how long to wait for data before considering disconnected (ms)
-read_timeout = 10000
-
-# Heartbeat interval (ms). The streaming protocol requires pings every 100ms.
-ping_interval = 100
-
-# Reconnect wait after involuntary disconnect (ms)
-# FPSSClient.RECONNECT_DELAY_MS = 2000 at runtime in the Java terminal.
-reconnect_wait = 2000
+# Read timeout — how long to wait for data before the link is considered
+# dead (ms). The server heartbeats every ~100 ms on a quiet session, so this
+# default is ~30 missed heartbeats: a dead link is declared quickly.
+read_timeout = 3000
+
+# Client heartbeat interval (ms). The server's own ~100 ms heartbeat is the
+# primary liveness signal; this client ping proves write-side health at a
+# 4 Hz cadence without adding inbound-frame pressure on a recovering upstream.
+ping_interval = 250
+
+# Initial reconnect wait after an involuntary disconnect (ms). The auto-
+# reconnect driver doubles this per consecutive attempt up to its cap, then
+# applies jitter so a fleet does not reconnect in lockstep.
+reconnect_wait = 250
 
 # Reconnect wait after TooManyRequests (ms). ThetaData enforces rate limits.
 reconnect_wait_rate_limited = 130000
diff --git a/crates/thetadatadx/src/config/mod.rs b/crates/thetadatadx/src/config/mod.rs
@@ -1287,6 +1287,80 @@ mod tests {
             assert_eq!(config.streaming.hosts.len(), 4);
         }
 
+        #[test]
+        fn config_default_toml_matches_production_defaults() {
+            // The shipped template fills every tuning knob explicitly, and
+            // `#[serde(default)]` only backfills absent keys — so any value
+            // written here OVERRIDES the code default the moment an operator
+            // copies the file. Pin every parsed value to
+            // `DirectConfig::production()` so the template can never silently
+            // drift from the in-code defaults.
+            let default_toml = include_str!("../../config.default.toml");
+            let config = DirectConfig::from_toml_str(default_toml).unwrap();
+            let prod = DirectConfig::production();
+
+            // Historical (gRPC).
+            assert_eq!(config.historical.host, prod.historical.host);
+            assert_eq!(config.historical.port, prod.historical.port);
+            assert_eq!(config.historical.tls, prod.historical.tls);
+            assert_eq!(
+                config.historical.keepalive_secs,
+                prod.historical.keepalive_secs
+            );
+            assert_eq!(
+                config.historical.keepalive_timeout_secs,
+                prod.historical.keepalive_timeout_secs
+            );
+            assert_eq!(
+                config.historical.max_message_size,
+                prod.historical.max_message_size
+            );
+            assert_eq!(
+                config.historical.window_size_kb,
+                prod.historical.window_size_kb
+            );
+            assert_eq!(
+                config.historical.connection_window_size_kb,
+                prod.historical.connection_window_size_kb
+            );
+            assert_eq!(
+                config.historical.concurrent_requests,
+                prod.historical.concurrent_requests
+            );
+
+            // Streaming (TCP).
+            assert_eq!(config.streaming.hosts, prod.streaming.hosts);
+            assert_eq!(
+                config.streaming.connect_timeout_ms,
+                prod.streaming.connect_timeout_ms
+            );
+            assert_eq!(config.streaming.timeout_ms, prod.streaming.timeout_ms);
+            assert_eq!(
+                config.streaming.ping_interval_ms,
+                prod.streaming.ping_interval_ms
+            );
+            assert_eq!(config.streaming.ring_size, prod.streaming.ring_size);
+            assert_eq!(config.streaming.flush_mode, prod.streaming.flush_mode);
+            assert_eq!(config.streaming.wait_strategy, prod.streaming.wait_strategy);
+            assert_eq!(
+                config.streaming.wait_spin_iters,
+                prod.streaming.wait_spin_iters
+            );
+            assert_eq!(
+                config.streaming.wait_yield_iters,
+                prod.streaming.wait_yield_iters
+            );
+            assert_eq!(config.streaming.wait_park_us, prod.streaming.wait_park_us);
+            assert_eq!(config.streaming.consumer_cpu, prod.streaming.consumer_cpu);
+
+            // Reconnect cadence.
+            assert_eq!(config.reconnect.wait_ms, prod.reconnect.wait_ms);
+            assert_eq!(
+                config.reconnect.wait_rate_limited_ms,
+                prod.reconnect.wait_rate_limited_ms
+            );
+        }
+
         #[test]
         fn config_default_toml_uses_canonical_section_names() {
             // The deserializer binds `[historical]` / `[streaming]`; the
diff --git a/docs-site/docs/articles/concurrent-requests.md b/docs-site/docs/articles/concurrent-requests.md
@@ -27,7 +27,7 @@ from thetadatadx import AsyncClient
 client = AsyncClient.from_file("creds.txt")
 
 async def pull(day):
-    return await client.historical.stock_history_trade_async("AAPL", day)
+    return await client.stock_history_trade_async("AAPL", day)
 
 results = asyncio.run(asyncio.gather(*(pull(d) for d in days)))
 ```
diff --git a/docs-site/docs/articles/getting-started.md b/docs-site/docs/articles/getting-started.md
@@ -5,7 +5,7 @@ description: Install the SDK, save your credentials, and make your first request
 
 # Getting Started
 
-ThetaDataDx connects directly to ThetaData's servers — no Java terminal process to install or babysit. Pick a language, install, save your credentials, and make a request.
+ThetaDataDx connects directly to ThetaData's servers — nothing to install and babysit locally. Pick a language, install, save your credentials, and make a request.
 
 ## 1. Install
 
diff --git a/docs-site/docs/cli.md b/docs-site/docs/cli.md
@@ -26,7 +26,7 @@ thetadatadx option list_expirations SPY
 thetadatadx option list_strikes SPY 20250321
 
 # EOD Greeks for one pinned contract
-thetadatadx option history_greeks_eod SPY 20250321 570 C 20250303 20250306
+thetadatadx option history_greeks_eod SPY 20250321 20250303 20250306 570 C
 
 # Snapshot quotes for several symbols
 thetadatadx stock snapshot_quote AAPL,MSFT,GOOGL
diff --git a/docs-site/docs/examples/bulk-backfill.md b/docs-site/docs/examples/bulk-backfill.md
@@ -39,7 +39,7 @@ Every endpoint has a `<endpoint>_builder(...)` factory whose `.stream(...)` / `.
 ```rust
 let days = ["20250303", "20250304", "20250305"];
 for day in days {
-    client.historical.stock_history_trade("AAPL", day)
+    client.historical().stock_history_trade("AAPL", day)
         .stream(|chunk| {
             // &[TradeTick] — persist, then the chunk is dropped.
             write_parquet(chunk);
diff --git a/docs-site/docs/server/index.md b/docs-site/docs/server/index.md
@@ -9,7 +9,7 @@ description: Run the local HTTP REST and WebSocket server speaking the v3 route
 
 ## Download and run
 
-Prebuilt binaries are attached to each [GitHub Release](https://github.com/userFRM/ThetaDataDx/releases). No Rust toolchain and no Java terminal are required — download the archive for your platform, unpack it, and run the binary.
+Prebuilt binaries are attached to each [GitHub Release](https://github.com/userFRM/ThetaDataDx/releases). No Rust toolchain and nothing else to install locally — download the archive for your platform, unpack it, and run the binary.
 
 The binaries are not code-signed yet, so each operating system asks for a one-time confirmation the first time you launch one.
 
diff --git a/sdks/cpp/README.md b/sdks/cpp/README.md
@@ -1,6 +1,6 @@
 # thetadatadx (C++)
 
-The C++ SDK for [ThetaData](https://thetadata.us) market data. Pull US stock, option, index, and rate data three ways — point-in-time **history**, real-time **streaming**, and whole-universe **flat files** — all from a single authenticated client. Connects straight to ThetaData; no Java terminal, no JVM, no local proxy.
+The C++ SDK for [ThetaData](https://thetadata.us) market data. Pull US stock, option, index, and rate data three ways — point-in-time **history**, real-time **streaming**, and whole-universe **flat files** — all from a single authenticated client. Connects straight to ThetaData; nothing to install and run locally, no local proxy.
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/userFRM/ThetaDataDx/blob/main/LICENSE)
 [![C++](https://img.shields.io/badge/C%2B%2B-17-00599C.svg?logo=cplusplus&logoColor=white)](https://isocpp.org)
@@ -12,10 +12,10 @@ The C++ SDK for [ThetaData](https://thetadata.us) market data. Pull US stock, op
 
 ## Features
 
-- **Complete coverage** — stocks, options, indices, and rates across 61 typed endpoints.
+- **Complete coverage** — stocks, options, indices, and rates across 65 typed endpoints.
 - **Three access modes** — point-in-time history, real-time streaming, and bulk flat-file downloads.
 - **Typed structs, no JSON** — every endpoint returns a `std::vector` of decoded structs; prices arrive as `double`.
-- **Greeks without a round-trip** — 23 Black-Scholes Greeks and an implied-volatility solver, computed locally.
+- **Greeks without a round-trip** — first- through third-order Black-Scholes Greeks and an implied-volatility solver, computed locally.
 - **RAII throughout** — clients own their connections and clean up on scope exit; methods throw on failure.
 - **Header plus one library** — a single `thetadatadx.hpp` over a prebuilt C ABI shared library.
 
@@ -157,7 +157,7 @@ fpss.subscribe(thetadatadx::SecType::option().full_trades());   // the callback
 
 ## Greeks calculator
 
-A full Black-Scholes calculator — 23 Greeks plus an implied-volatility solver — runs locally, no connection required:
+A full Black-Scholes calculator — first- through third-order Greeks plus an implied-volatility solver — runs locally, no connection required:
 
 ```cpp
 auto g = thetadatadx::all_greeks(450.0, 455.0, 0.05, 0.015, 30.0 / 365.0, 8.50, "C");
@@ -191,12 +191,12 @@ The flat-file distribution serves a fixed set of datasets: option `trade_quote`
 
 ## Endpoint coverage
 
-61 typed endpoints across stocks, options, indices, the market calendar, and interest rates, plus real-time streaming and the local Greeks calculator.
+65 typed endpoints across stocks, options, indices, the market calendar, and interest rates, plus real-time streaming and the local Greeks calculator.
 
 | Category | Endpoints | Examples |
 |---|---|---|
-| Stock | 14 | EOD, OHLC, trades, quotes, snapshots, at-time |
-| Option | 34 | Every stock surface plus five Greeks tiers, open interest, contract lists |
+| Stock | 16 | EOD, OHLC, trades, quotes, snapshots, at-time |
+| Option | 36 | Every stock surface plus five Greeks tiers, open interest, contract lists |
 | Index | 9 | EOD, OHLC, price, snapshots |
 | Calendar | 3 | Market open/close, holidays, early closes |
 | Interest rate | 1 | EOD rate history |
diff --git a/sdks/python/README.md b/sdks/python/README.md
diff --git a/sdks/python/examples/historical.py b/sdks/python/examples/historical.py
diff --git a/sdks/typescript/README.md b/sdks/typescript/README.md
diff --git a/sdks/typescript/examples/historical.ts b/sdks/typescript/examples/historical.ts
diff --git a/sdks/typescript/scripts/run_doc_examples.mjs b/sdks/typescript/scripts/run_doc_examples.mjs
