v3.0.0: unified ThetaDataDx client -- one connect, lazy streaming

Breaking:
- ThetaDataDx replaces DirectClient + FpssClient as the public API
- Connect once, auth once. Historical immediately, streaming on demand.
- Python: DirectClient and FpssClient classes removed. Use ThetaDataDx.

Added:
- ThetaDataDx::connect(creds, config) -- single entry point
- start_streaming / start_streaming_no_ohlcvc -- lazy FPSS
- stop_streaming -- clean shutdown, historical stays alive
- Explicit Drop impl stops streaming automatically
- FFI: tdx_unified_connect, tdx_unified_historical (repr(transparent) cast)
- C++ SDK: 9 new typed structs, all 61 methods return vector<T>
- Go SDK: 9 new typed structs, all 63 methods return []T
- Python: _df DataFrame methods on ThetaDataDx
- Server: stop_streaming on graceful shutdown

Fixed:
- All audit findings (critical/high/medium/low) from dual Codex+Gemini review
- No raw JSON in any SDK public API surface
- All docs, notebooks, READMEs match actual API signatures

160 tests, zero warnings.

Author: userFRM

.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,7 +21,7 @@ A clear and concise description of the bug.
 
 ## Endpoint / Method Affected
 
-Which API endpoint or client method is involved? (e.g., `DirectClient::get_quotes`, `FpssClient::subscribe`)
+Which API endpoint or client method is involved? (e.g., `ThetaDataDx::stock_history_eod`, `ThetaDataDx::subscribe_quotes`)
 
 ## Steps to Reproduce
 

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-03-27
+
+### Breaking Changes
+
+- **Unified `ThetaDataDx` client** — single entry point replacing `DirectClient` + `FpssClient`.
+  Connect once, auth once. Historical available immediately, streaming connects lazily.
+- **`DirectClient` removed from crate root re-exports** — still accessible as `thetadatadx::direct::DirectClient` but all methods available via `ThetaDataDx` (Deref)
+- **`FpssClient` removed from crate root re-exports** — use `tdx.start_streaming(handler)` instead
+- **Python SDK**: `DirectClient` and `FpssClient` classes removed. Use `ThetaDataDx` only.
+
+### Added
+
+- `ThetaDataDx::connect(creds, config)` — one auth, gRPC channel ready, no FPSS yet
+- `tdx.start_streaming(handler)` — lazy FPSS connection on demand
+- `tdx.start_streaming_no_ohlcvc(handler)` — same, without derived OHLCVC
+- `tdx.stop_streaming()` — clean shutdown of streaming, historical stays alive
+- `tdx.is_streaming()` — check if FPSS is active
+- All 61 historical methods via `Deref<Target = DirectClient>`
+- All streaming methods (subscribe/unsubscribe) directly on `ThetaDataDx`
+- FFI: `tdx_unified_connect()`, `tdx_unified_start_streaming()`, `tdx_unified_stop_streaming()`
+- Server: graceful `stop_streaming()` on shutdown
+
+### Fixed
+
+- Server shutdown now calls `stop_streaming()` before notifying waiters
+- Python SDK: removed duplicate method definitions (DirectClient + ThetaDataDx had same methods)
+
 ## [2.0.0] - 2026-03-27
 
 ### New Products
@@ -312,7 +339,9 @@ See [TODO.md](TODO.md) for the production readiness checklist and performance ro
 - FIT decoder uses i64 accumulator with i32 saturation (no silent overflow)
 - Price type range enforced with `assert!` in release builds
 
-[Unreleased]: https://github.com/userFRM/ThetaDataDx/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/userFRM/ThetaDataDx/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/userFRM/ThetaDataDx/compare/v2.0.0...v3.0.0
+[2.0.0]: https://github.com/userFRM/ThetaDataDx/compare/v1.2.2...v2.0.0
 [1.2.2]: https://github.com/userFRM/ThetaDataDx/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/userFRM/ThetaDataDx/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/userFRM/ThetaDataDx/compare/v1.1.1...v1.2.0

CONTRIBUTING.md

@@ -82,7 +82,7 @@ Adding a new endpoint is a single macro invocation -- no hand-coded boilerplate.
    - Add the corresponding `extern "C"` function in `ffi/src/lib.rs`
    - The FFI crate also uses macros for endpoint generation -- follow the existing pattern
    - For FPSS-related functions, see the 7 existing `thetadatadx_fpss_*` functions as examples
-   - Update the C header, Go SDK (`FpssClient`), and C++ SDK (`FpssClient`) wrappers accordingly
+   - Update the C header, Go SDK, and C++ SDK wrappers accordingly
 
 4. **Expose in the Python SDK**
    - Add the PyO3 binding in `sdks/python/src/`

Cargo.lock

@@ -34,7 +34,7 @@ No-JVM ThetaData Terminal — native Rust SDK for direct market data access.
 
 ```toml
 [dependencies]
-thetadatadx = "2.0"
+thetadatadx = "3.0"
 tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
 ```
 
@@ -53,23 +53,23 @@ pip install thetadatadx[pandas]
 > Create a `creds.txt` file with your ThetaData email on line 1 and password on line 2. This is the same format the Java terminal uses.
 
 ```rust
-use thetadatadx::{DirectClient, Credentials, DirectConfig};
+use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
 
 #[tokio::main]
 async fn main() -> Result<(), thetadatadx::Error> {
     let creds = Credentials::from_file("creds.txt")?;
-    let client = DirectClient::connect(&creds, DirectConfig::production()).await?;
+    let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
 
     // Fetch end-of-day stock data
-    let eod = client.stock_history_eod("AAPL", "20240101", "20240301").await?;
+    let eod = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;
     for tick in &eod {
         println!("{}: O={} H={} L={} C={} V={}",
             tick.date, tick.open_price(), tick.high_price(),
             tick.low_price(), tick.close_price(), tick.volume);
     }
 
     // List option expirations
-    let exps = client.option_list_expirations("SPY").await?;
+    let exps = tdx.option_list_expirations("SPY").await?;
     println!("SPY expirations: {:?}", &exps[..5.min(exps.len())]);
 
     Ok(())
@@ -82,14 +82,17 @@ async fn main() -> Result<(), thetadatadx::Error> {
 > FPSS streaming connects to ThetaData's dedicated streaming servers via TLS/TCP. The client automatically sends heartbeat pings every 100ms as required by the protocol.
 
 ```rust
-use thetadatadx::auth::Credentials;
-use thetadatadx::fpss::{FpssClient, FpssData, FpssControl, FpssEvent};
+use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
+use thetadatadx::fpss::{FpssData, FpssControl, FpssEvent};
 use thetadatadx::fpss::protocol::Contract;
 
 #[tokio::main]
 async fn main() -> Result<(), thetadatadx::Error> {
     let creds = Credentials::from_file("creds.txt")?;
-    let client = FpssClient::connect(&creds, 1024, |event: &FpssEvent| {
+    let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
+
+    // Start streaming with a callback
+    tdx.start_streaming(|event: &FpssEvent| {
         match event {
             FpssEvent::Data(FpssData::Quote { contract_id, bid, ask, .. }) => {
                 println!("Quote: contract={contract_id} bid={bid} ask={ask}");
@@ -104,11 +107,12 @@ async fn main() -> Result<(), thetadatadx::Error> {
         }
     })?;
 
-    let req_id = client.subscribe_quotes(&Contract::stock("AAPL"))?;
-    println!("Subscribed (req_id={req_id})");
+    tdx.subscribe_quotes(&Contract::stock("AAPL"))?;
+    println!("Subscribed to AAPL quotes");
 
     // Block until shutdown
     std::thread::park();
+    tdx.stop_streaming();
     Ok(())
 }
 ```
@@ -237,7 +241,7 @@ async fn main() -> Result<(), thetadatadx::Error> {
 ## Configuration
 
 ```rust
-use thetadatadx::DirectConfig;
+use thetadatadx::{ThetaDataDx, DirectConfig};
 
 // Production (ThetaData NJ datacenter, gRPC over TLS)
 let config = DirectConfig::production();

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx"
-version = "2.0.0"
+version = "3.0.0"
 edition = "2021"
 rust-version = "1.85"
 authors = ["userFRM"]

crates/thetadatadx/Cargo.toml

@@ -202,13 +202,13 @@ macro_rules! contract_spec {
 /// # Example
 ///
 /// ```rust,no_run
-/// use thetadatadx::{DirectClient, Credentials, DirectConfig};
+/// use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
 ///
 /// # async fn run() -> Result<(), thetadatadx::Error> {
 /// let creds = Credentials::from_file("creds.txt")?;
-/// let client = DirectClient::connect(&creds, DirectConfig::production()).await?;
+/// let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
 ///
-/// let eod = client.stock_history_eod("AAPL", "20240101", "20240301").await?;
+/// let eod = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;
 /// println!("{} EOD ticks", eod.len());
 /// # Ok(())
 /// # }
@@ -1906,7 +1906,7 @@ impl DirectClient {
     /// # Example
     ///
     /// ```rust,no_run
-    /// # async fn run(client: &thetadatadx::DirectClient) -> Result<(), thetadatadx::Error> {
+    /// # async fn run(client: &thetadatadx::direct::DirectClient) -> Result<(), thetadatadx::Error> {
     /// use thetadatadx::proto_v3;
     ///
     /// let request = proto_v3::CalendarYearRequest {

crates/thetadatadx/src/direct.rs

@@ -18,23 +18,53 @@
 //!
 //! ## Quick Start
 //!
+//! The recommended entry point is [`ThetaDataDx`], which authenticates once and
+//! provides both historical and streaming through a single object:
+//!
 //! ```rust,ignore
-//! use thetadatadx::{DirectClient, Credentials, DirectConfig};
+//! use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
+//! use thetadatadx::fpss::{FpssData, FpssControl, FpssEvent};
+//! use thetadatadx::fpss::protocol::Contract;
 //!
 //! #[tokio::main]
 //! async fn main() -> Result<(), thetadatadx::Error> {
 //!     let creds = Credentials::from_file("creds.txt")?;
-//!     let client = DirectClient::connect(&creds, DirectConfig::production()).await?;
 //!
-//!     // Historical data (MDDS/gRPC)
-//!     let ticks = client.stock_history_eod("AAPL", "20240101", "20240301").await?;
+//!     // Connect -- authenticates once, historical ready immediately
+//!     let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
+//!
+//!     // Historical (MDDS gRPC) -- all 61 methods via Deref
+//!     let ticks = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;
+//!
+//!     // Streaming (FPSS TCP) -- connects lazily on first call
+//!     tdx.start_streaming(|event: &FpssEvent| {
+//!         match event {
+//!             FpssEvent::Data(FpssData::Trade { contract_id, price, size, .. }) => {
+//!                 println!("Trade: {contract_id} @ {price} x {size}");
+//!             }
+//!             _ => {}
+//!         }
+//!     })?;
 //!
-//!     // Real-time streaming (FPSS/TCP)
-//!     // let stream = client.subscribe_quotes("AAPL").await?;
+//!     tdx.subscribe_quotes(&Contract::stock("AAPL"))?;
+//!
+//!     // ... when done:
+//!     tdx.stop_streaming();
 //!     Ok(())
 //! }
 //! ```
 //!
+//! For historical-only usage, just skip `start_streaming()` -- all 61 historical
+//! methods are available directly on `ThetaDataDx` via `Deref<Target = DirectClient>`:
+//!
+//! ```rust,ignore
+//! use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
+//!
+//! let creds = Credentials::from_file("creds.txt")?;
+//! let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
+//! let ticks = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;
+//! ```
+//!
 //! ## Reverse-Engineering Notes
 //!
 //! This crate was built by decompiling ThetaData's Java terminal (v202603181, 58.5MB):
@@ -73,6 +103,7 @@ pub mod fpss;
 pub mod greeks;
 pub mod registry;
 pub mod types;
+pub mod unified;
 
 /// Generated protobuf types from `endpoints.proto` (shared types).
 ///
@@ -97,6 +128,6 @@ pub mod proto_v3 {
 
 pub use auth::Credentials;
 pub use config::DirectConfig;
-pub use direct::DirectClient;
 pub use error::Error;
 pub use registry::{EndpointMeta, ParamMeta, ParamType, ReturnType, ENDPOINTS};
+pub use unified::ThetaDataDx;