refactor(streaming): fluent contract-first API + ThetaDataClient rename

Hard break: every typed `subscribe_*` / `unsubscribe_*` /
`subscribe_option_*` method on the public surface and every typed
`tdx_*_subscribe_*` / `tdx_*_unsubscribe_*` C ABI entry point is
deleted. The unified surface now ships only the polymorphic
`subscribe(Subscription)` / `unsubscribe(Subscription)` /
`subscribe_many([...])` / `unsubscribe_many([...])` paths plus the
fluent `Contract::stock(...)` / `Contract::option(...)` /
`SecType::Option.full_trades()` value constructors that feed them.

Public client name is `ThetaDataClient` across every binding (Rust
struct, Python pyclass, TypeScript napi class). The previous unified
struct name is gone — no alias, no compat shim. Python also gains
`AsyncThetaDataClient` as the async-only sibling that filters
attribute access to `*_async` historical methods plus the streaming
lifecycle helpers.

Polymorphic C ABI: `tdx_unified_subscribe` / `tdx_unified_unsubscribe`
/ `tdx_fpss_subscribe` / `tdx_fpss_unsubscribe` take a
`TdxSubscriptionRequest` payload (scope + kind + per-contract or
full-stream fields). One entry point handles every variant; the
generated C++ wrappers reach the same surface through the existing
`tdx::Contract` / `tdx::SecType` fluent value types.

The `sdk_surface.toml` codegen spec drops the typed entries; the
regenerated `streaming_methods.rs` for both Python and TypeScript
contains zero `subscribe_*` typed methods. CHANGELOG carries the
documentation-only migration map old → new (no compat layer ships).

Tests: 553 unit / integration tests pass, fmt + clippy clean,
`generate_sdk_surfaces --check` returns zero diff. C++ static
library builds.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: userFRM

CHANGELOG.md

@@ -1,8 +1,8 @@
-# ThetaDataDx
+# ThetaDataClient
 
 Rust SDK for ThetaData market data — single Rust core, four language surfaces (Rust, Python, TypeScript, C++).
 
-[![build](https://github.com/userFRM/ThetaDataDx/actions/workflows/ci.yml/badge.svg)](https://github.com/userFRM/ThetaDataDx/actions/workflows/ci.yml)
+[![build](https://github.com/userFRM/ThetaDataClient/actions/workflows/ci.yml/badge.svg)](https://github.com/userFRM/ThetaDataClient/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![Crates.io](https://img.shields.io/crates/v/thetadatadx.svg)](https://crates.io/crates/thetadatadx)
 [![PyPI](https://img.shields.io/pypi/v/thetadatadx)](https://pypi.org/project/thetadatadx)
@@ -48,12 +48,12 @@ tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
 ```
 
 ```rust
-use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
+use thetadatadx::{ThetaDataClient, Credentials, DirectConfig};
 
 #[tokio::main]
 async fn main() -> Result<(), thetadatadx::Error> {
     let creds = Credentials::from_file("creds.txt")?;
-    let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
+    let tdx = ThetaDataClient::connect(&creds, DirectConfig::production()).await?;
     let eod = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;
     for tick in &eod {
         println!("{}: O={} H={} L={} C={} V={}",
@@ -86,9 +86,9 @@ pip install thetadatadx
 ```
 
 ```python
-from thetadatadx import Credentials, Config, ThetaDataDx
+from thetadatadx import Credentials, Config, ThetaDataClient
 
-tdx = ThetaDataDx(Credentials.from_file("creds.txt"), Config.production())
+tdx = ThetaDataClient(Credentials.from_file("creds.txt"), Config.production())
 for tick in tdx.stock_history_eod("AAPL", "20240101", "20240301"):
     print(f"{tick.date}: O={tick.open:.2f} H={tick.high:.2f} "
           f"L={tick.low:.2f} C={tick.close:.2f} V={tick.volume}")
@@ -101,9 +101,9 @@ npm install thetadatadx
 ```
 
 ```typescript
-import { ThetaDataDx } from 'thetadatadx';
+import { ThetaDataClient } from 'thetadatadx';
 
-const tdx = await ThetaDataDx.connectFromFile('creds.txt');
+const tdx = await ThetaDataClient.connectFromFile('creds.txt');
 for (const t of tdx.stockHistoryEOD('AAPL', '20240101', '20240301')) {
     console.log(`${t.date}: O=${t.open} H=${t.high} L=${t.low} C=${t.close} V=${t.volume}`);
 }
@@ -116,7 +116,7 @@ for (const t of tdx.stockHistoryEOD('AAPL', '20240101', '20240301')) {
 #include <cstdio>
 
 int main() {
-    auto tdx = thetadatadx::ThetaDataDx::connect_from_file("creds.txt");
+    auto tdx = thetadatadx::ThetaDataClient::connect_from_file("creds.txt");
     for (const auto& t : tdx.stock_history_eod("AAPL", "20240101", "20240301")) {
         std::printf("%d: O=%.2f H=%.2f L=%.2f C=%.2f V=%lld\n",
             t.date, t.open, t.high, t.low, t.close, (long long)t.volume);
@@ -128,9 +128,13 @@ int main() {
 
 One connection, one auth. Historical queries are available immediately; streaming connects lazily on first subscription. The client auto-reconnects and re-subscribes all active contracts on involuntary disconnect.
 
+The primary streaming surface is the **fluent contract-first API** —
+`Contract::stock("AAPL").quote()` returns a typed `Subscription` value
+that the polymorphic `client.subscribe(...)` accepts directly:
+
 ```rust
 use thetadatadx::fpss::{FpssData, FpssEvent};
-use thetadatadx::fpss::protocol::Contract;
+use thetadatadx::prelude::*;
 
 tdx.start_streaming(|event: &FpssEvent| {
     match event {
@@ -140,20 +144,24 @@ tdx.start_streaming(|event: &FpssEvent| {
         FpssEvent::Data(FpssData::Trade { contract, price, size, .. }) => {
             println!("Trade: {} @ {price} x {size}", contract.symbol);
         }
-        FpssEvent::Data(FpssData::Ohlcvc { contract, open, high, low, close, volume, .. }) => {
-            println!(
-                "OHLCVC: {} O={open} H={high} L={low} C={close} V={volume}",
-                contract.symbol,
-            );
-        }
         _ => {}
     }
 })?;
 
-tdx.subscribe_quotes(&Contract::stock("AAPL"))?;
-tdx.subscribe_trades(&Contract::stock("AAPL"))?;
+let stock  = Contract::stock("AAPL");
+let option = Contract::option("SPY", "20260620", "550", "C")?;
+
+tdx.subscribe(stock.quote())?;
+tdx.subscribe(option.trade())?;
+tdx.subscribe(SecType::Option.full_open_interest())?;
+
+// Bulk install:
+tdx.subscribe_many(vec![stock.quote(), option.quote()])?;
 ```
 
+All prices (`bid`, `ask`, `price`, `open`, `high`, `low`, `close`) are `f64`, decoded during parsing.
+
+
 All prices (`bid`, `ask`, `price`, `open`, `high`, `low`, `close`) are `f64`, decoded during parsing.
 
 ## API coverage

README.md

@@ -49,7 +49,7 @@ println!("IV: {:.4}, Delta: {:.4}", result.iv, result.delta);
 
 `thetadatadx` depends on `tdbe` for all data types and codecs, then adds
 networking (gRPC historical via MDDS, real-time streaming via FPSS), authentication,
-and the unified `ThetaDataDx` client. If you only need types and offline Greeks,
+and the unified `ThetaDataClient` client. If you only need types and offline Greeks,
 depend on `tdbe` alone.
 
 ## License

crates/tdbe/README.md

@@ -117,7 +117,7 @@ serde_json = "1.0.137"
 zeroize = { version = "1.8.2", features = ["derive"] }
 
 # Lock-free atomic swap of an `Arc<StreamingSlot>` for the streaming
-# state machine on `ThetaDataDx`. Carries the `Arc<FpssClient>` so the
+# state machine on `ThetaDataClient`. Carries the `Arc<FpssClient>` so the
 # hot read paths (`is_streaming`, `connection_status`,
 # `dropped_event_count`, `panic_count`, `with_streaming`) all collapse
 # to a single `state.load()`.

crates/thetadatadx/Cargo.toml

@@ -2,23 +2,23 @@
 
 Core Rust crate — direct wire-protocol access to all three of ThetaData's public surfaces: MDDS (request/response history over gRPC), FPSS (real-time streaming over TCP), and FLATFILES (whole-universe daily blobs over the legacy MDDS port).
 
-This is the engine that powers all ThetaDataDx SDKs (Python, TypeScript / Node.js, C++, CLI, MCP, REST server).
+This is the engine that powers all ThetaDataClient SDKs (Python, TypeScript / Node.js, C++, CLI, MCP, REST server).
 
 ## Entry Point
 
 ```rust
-use thetadatadx::{ThetaDataDx, Credentials, DirectConfig};
+use thetadatadx::{ThetaDataClient, Credentials, DirectConfig};
 use thetadatadx::fpss::protocol::Contract;
 
 let creds = Credentials::from_file("creds.txt")?;
-let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
+let tdx = ThetaDataClient::connect(&creds, DirectConfig::production()).await?;
 
 // Historical - typed endpoints available immediately
 let eod = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;
 
 // Streaming - connects lazily on first call
 tdx.start_streaming(|event| { /* ... */ })?;
-tdx.subscribe_quotes(&Contract::stock("AAPL"))?;
+tdx.subscribe(Contract::stock("AAPL").quote())?;
 
 // When done
 tdx.stop_streaming();
@@ -35,14 +35,14 @@ let rows = tdx
     .await?;
 ```
 
-`ThetaDataDx::connect()` authenticates once. Historical data (MDDS gRPC) is available immediately via `Deref` to the internal `MddsClient`. Streaming (FPSS TCP) connects lazily when you call `start_streaming()`. Flat-file requests (FLATFILES) open a per-call TLS connection to the legacy MDDS port and are independent of the MDDS gRPC and FPSS sessions — see [vendor docs](https://http-docs.thetadata.us/operations/get-v2-flat-file-getting-started.html) for the full flat-file matrix.
+`ThetaDataClient::connect()` authenticates once. Historical data (MDDS gRPC) is available immediately via `Deref` to the internal `MddsClient`. Streaming (FPSS TCP) connects lazily when you call `start_streaming()`. Flat-file requests (FLATFILES) open a per-call TLS connection to the legacy MDDS port and are independent of the MDDS gRPC and FPSS sessions — see [vendor docs](https://http-docs.thetadata.us/operations/get-v2-flat-file-getting-started.html) for the full flat-file matrix.
 
 ## Crate Layout
 
 ```
 src/
-  lib.rs           - public re-exports (ThetaDataDx, Credentials, DirectConfig, Error)
-  unified.rs       - ThetaDataDx: single entry point, lazy streaming
+  lib.rs           - public re-exports (ThetaDataClient, Credentials, DirectConfig, Error)
+  unified.rs       - ThetaDataClient: single entry point, lazy streaming
   mdds/            - MddsClient module (client, stream, validate, normalize, endpoints)
   auth/            - Nexus API authentication, credential parsing
   fpss/            - FPSS streaming client (sync, LMAX Disruptor ring buffer)

crates/thetadatadx/README.md

@@ -1,12 +1,12 @@
 //! Python SDK `#[pymethods]` emitter.
 //!
-//! Renders `sdks/python/src/historical_methods.rs` — the `ThetaDataDx` impl
+//! Renders `sdks/python/src/historical_methods.rs` — the `ThetaDataClient` impl
 //! block that PyO3 compiles into the Python extension.
 //!
 //! Every method takes a `timeout_ms: Optional[int]` kwarg. When set the
 //! call is given a deadline; on expiry a `RuntimeError` carrying the
 //! `Error::Timeout` message is raised and the underlying gRPC stream is
-//! cancelled. The `ThetaDataDx` handle remains usable for subsequent calls.
+//! cancelled. The `ThetaDataClient` handle remains usable for subsequent calls.
 //!
 //! # Three variants per endpoint (sync / async / fluent builder)
 //!
@@ -82,7 +82,7 @@ pub(super) fn render_python_decode_bench(endpoints: &[GeneratedEndpoint]) -> Str
 
     // The pyfunction itself.
     out.push_str("/// Decode recorded gRPC response bytes into the same typed pyclass list\n");
-    out.push_str("/// the matching `ThetaDataDx` endpoint would have returned.\n");
+    out.push_str("/// the matching `ThetaDataClient` endpoint would have returned.\n");
     out.push_str("///\n");
     out.push_str("/// `endpoint` must match an endpoint name from `endpoint_surface.toml` that\n");
     out.push_str(
@@ -163,7 +163,7 @@ pub(super) fn render_python_historical_methods(endpoints: &[GeneratedEndpoint])
         "// @generated DO NOT EDIT — regenerated by build.rs from endpoint_surface.toml\n\n",
     );
 
-    // Per-endpoint fluent builder pyclasses. Emitted BEFORE the `ThetaDataDx`
+    // Per-endpoint fluent builder pyclasses. Emitted BEFORE the `ThetaDataClient`
     // impl block so `add_class::<HistoricalBuilder>()` at module-init time sees
     // the types. One struct per endpoint; each has chained setters for the
     // optional params, required params captured at construction time, and
@@ -199,7 +199,7 @@ pub(super) fn render_python_historical_methods(endpoints: &[GeneratedEndpoint])
     out.push_str("}\n\n");
 
     out.push_str("#[pymethods]\n");
-    out.push_str("impl ThetaDataDx {\n");
+    out.push_str("impl ThetaDataClient {\n");
     for endpoint in endpoints
         .iter()
         .filter(|endpoint| !is_streaming_endpoint(endpoint))
@@ -486,7 +486,7 @@ fn render_python_endpoint_async(endpoint: &GeneratedEndpoint) -> String {
     out.push_str("        timeout_ms: Option<u64>,\n");
     out.push_str("    ) -> PyResult<Bound<'py, PyAny>> {\n");
 
-    // Clone the Arc<thetadatadx::ThetaDataDx> handle into the closure — the
+    // Clone the Arc<thetadatadx::ThetaDataClient> handle into the closure — the
     // inner client is not Clone but the Arc is, and the builder pyclass
     // pattern elsewhere in this file relies on the same contract.
     out.push_str("        let tdx = self.tdx.clone();\n");
@@ -689,8 +689,8 @@ fn async_setter_arg_expr(param: &GeneratedParam) -> &'static str {
 //
 // The builder pattern is a Python-side ergonomics layer: chain setters,
 // terminate with `.arrow()` / `.list()` / `.polars()` / `.pandas()`. The
-// builder struct clones an `Arc<thetadatadx::ThetaDataDx>` from the owning
-// `ThetaDataDx` pyclass (see lib.rs where the field is wrapped in Arc for
+// builder struct clones an `Arc<thetadatadx::ThetaDataClient>` from the owning
+// `ThetaDataClient` pyclass (see lib.rs where the field is wrapped in Arc for
 // exactly this reason), so terminal calls can drive the existing endpoint
 // methods on the underlying client without re-authenticating or copying
 // configuration. State captured at builder construction time: required
@@ -761,9 +761,9 @@ fn render_python_endpoint_builder(endpoint: &GeneratedEndpoint) -> String {
     )
     .unwrap();
     writeln!(out, "pub struct {struct_name} {{").unwrap();
-    // Same Arc the parent `ThetaDataDx` pyclass stores — cheap to clone,
+    // Same Arc the parent `ThetaDataClient` pyclass stores — cheap to clone,
     // so the async terminal can move it into the future.
-    out.push_str("    tdx: std::sync::Arc<thetadatadx::ThetaDataDx>,\n");
+    out.push_str("    tdx: std::sync::Arc<thetadatadx::ThetaDataClient>,\n");
     for param in &method_params {
         if param.param_type == "Symbols" {
             out.push_str("    symbols: Vec<String>,\n");
@@ -940,7 +940,7 @@ fn render_python_endpoint_builder(endpoint: &GeneratedEndpoint) -> String {
     out
 }
 
-/// Builder constructor emitted on `ThetaDataDx` — `tdx.name_builder(...)` is
+/// Builder constructor emitted on `ThetaDataClient` — `tdx.name_builder(...)` is
 /// the Python entry point that yields a `NameBuilder`. Required params are
 /// passed positionally (same order as the typed endpoint); optionals are
 /// chained after construction.

crates/thetadatadx/build_support/endpoints/render/python.rs

@@ -17,21 +17,21 @@ baseline; bulk cells (`all_strikes_one_exp`, `bulk_chain` on option
 history / at-time endpoints) use 180 seconds because a full-chain
 payload legitimately takes longer than a minute. On expiry the in-flight
 gRPC stream is cancelled and a RuntimeError carrying "Request deadline
-exceeded" is raised. The `ThetaDataDx` handle stays usable for
+exceeded" is raised. The `ThetaDataClient` handle stays usable for
 subsequent cells.
 """
 import json
 import pathlib
 import sys
 import time
 
-from thetadatadx import Credentials, Config, ThetaDataDx
+from thetadatadx import Credentials, Config, ThetaDataClient
 
 PER_CELL_TIMEOUT_MS = 60_000
 SLOW_MODE_TIMEOUT_MS = 180_000
 ARTIFACT_PATH = pathlib.Path(__file__).resolve().parents[1] / "artifacts" / "validator_python.json"
 
-client = ThetaDataDx(Credentials.from_file(sys.argv[1]), Config.production())
+client = ThetaDataClient(Credentials.from_file(sys.argv[1]), Config.production())
 
 # (endpoint, mode_name, declared_min_tier, rationale, callable)
 # `declared_min_tier` is informational only (printed on tier-permission

crates/thetadatadx/build_support/endpoints/render/templates/validate_python/preamble.py.tmpl

@@ -1,11 +1,11 @@
 //! TypeScript SDK napi-rs emitter.
 //!
-//! Renders `sdks/typescript/src/historical_methods.rs` — the `ThetaDataDx`
+//! Renders `sdks/typescript/src/historical_methods.rs` — the `ThetaDataClient`
 //! impl block that napi-rs compiles into the Node.js native addon.
 //!
 //! Every method takes an optional `timeout_ms` parameter. When set, the call
 //! is given a deadline; on expiry a JS error is thrown and the underlying gRPC
-//! stream is cancelled. The `ThetaDataDx` handle remains usable.
+//! stream is cancelled. The `ThetaDataClient` handle remains usable.
 
 use std::fmt::Write as _;
 
@@ -23,7 +23,7 @@ pub(super) fn render_typescript_historical_methods(endpoints: &[GeneratedEndpoin
         "// @generated DO NOT EDIT — regenerated by build.rs from endpoint_surface.toml\n\n",
     );
     out.push_str("#[napi]\n");
-    out.push_str("impl ThetaDataDx {\n");
+    out.push_str("impl ThetaDataClient {\n");
     for endpoint in endpoints
         .iter()
         .filter(|endpoint| !is_streaming_endpoint(endpoint))

crates/thetadatadx/build_support/endpoints/render/typescript.rs

@@ -9,7 +9,7 @@ pub(super) fn render_python_streaming_methods(methods: &[&MethodSpec]) -> String
     let mut out = String::new();
     out.push_str(generated_header());
     out.push_str("#[pymethods]\n");
-    out.push_str("impl ThetaDataDx {\n");
+    out.push_str("impl ThetaDataClient {\n");
     for method in methods {
         out.push_str(&python_streaming_method(method));
         out.push('\n');
@@ -254,7 +254,7 @@ fn python_streaming_method(method: &MethodSpec) -> String {
                  Requires a prior `start_streaming(callback)`; raises\n\
                  `RuntimeError` if no callback is registered. All\n\
                  active subscriptions are restored on the new\n\
-                 connection — see `thetadatadx::ThetaDataDx::reconnect_streaming`\n\
+                 connection — see `thetadatadx::ThetaDataClient::reconnect_streaming`\n\
                  for partial-failure semantics.\n\
                  \n\
                  # Callback lifetime across `stop_streaming`\n\

crates/thetadatadx/build_support/sdk_surface/python.rs

@@ -1,5 +1,5 @@
 async fn try_execute_generated_utility(
-    client: Option<&ThetaDataDx>,
+    client: Option<&ThetaDataClient>,
     name: &str,
     args: &Value,
     start_time: std::time::Instant,