refactor: normalize endpoint request option surface

Author: userFRM

docs-site/docs/getting-started/migration-from-rest-ws.md

@@ -79,11 +79,11 @@ rows, err := client.OptionHistoryGreeksEODWithOptions(
     "C",
     "20221219",
     "20221220",
-    &thetadatadx.OptionRequestOptions{StrikeRange: thetadatadx.Int32(5)},
+    &thetadatadx.EndpointRequestOptions{StrikeRange: thetadatadx.Int32(5)},
 )
 ```
 ```cpp [C++]
-tdx::OptionRequestOptions options;
+tdx::EndpointRequestOptions options;
 options.strike_range = 5;
 auto rows = client.option_history_greeks_eod("SPY", "20230120", "0", "C", "20221219", "20221220", options);
 ```
@@ -218,7 +218,13 @@ The official streaming API exposes `STREAM` requests with `sec_type: "INDEX"` an
 
 ## Rust Builder vs Fixed-Arity Bindings
 
-Rust is the closest direct projection of the merged current REST routes because optional query parameters stay on builder methods.
+Rust is the closest direct projection of the merged current REST routes because required parameters stay in the constructor call and optional query parameters stay on builder methods. That chained style is intentional, not a special case for `strike_range`.
+
+Other SDKs project the same optional surface idiomatically for their language:
+
+- Python uses keyword-only optional parameters
+- Go uses `WithOptions` helpers plus `EndpointRequestOptions`
+- C++ uses `EndpointRequestOptions` overloads
 
 Example:
 
@@ -237,7 +243,7 @@ Python, Go, and C++ still expose fixed-arity convenience methods for the common
 
 - exact single-date helper when the binding exposes it
 - dedicated range helper when the binding exposes it, such as `stock_history_ohlc_range`
-- Python keyword-only optional parameters, Go `WithOptions` helpers, or C++ `OptionRequestOptions` overloads when the binding exposes them
+- Python keyword-only optional parameters, Go `WithOptions` helpers, or C++ `EndpointRequestOptions` overloads when the binding exposes them
 - Rust for the most faithful 1:1 projection of the official optional query surface
 
 ## Worked Example

docs-site/docs/historical/option/history/greeks-eod.md

@@ -44,15 +44,15 @@ data, _ := client.OptionHistoryGreeksEODWithOptions(
     "C",
     "20260101",
     "20260301",
-    &thetadatadx.OptionRequestOptions{StrikeRange: thetadatadx.Int32(5)},
+    &thetadatadx.EndpointRequestOptions{StrikeRange: thetadatadx.Int32(5)},
 )
 for _, t := range data {
     fmt.Printf("date=%d implied_volatility=%.4f delta=%.4f gamma=%.4f theta=%.4f vega=%.4f rho=%.4f\n",
         t.Date, t.ImpliedVolatility, t.Delta, t.Gamma, t.Theta, t.Vega, t.Rho)
 }
 ```
 ```cpp [C++]
-tdx::OptionRequestOptions options;
+tdx::EndpointRequestOptions options;
 options.strike_range = 5;
 auto data = client.option_history_greeks_eod("SPY", "20260417", "0", "C", "20260101", "20260301", options);
 for (const auto& t : data) {

ffi/src/lib.rs

@@ -118,7 +118,7 @@ pub struct TdxFpssHandle {
     rx: Arc<Mutex<std::sync::mpsc::Receiver<FfiBufferedEvent>>>,
 }
 
-/// Optional builder parameters for option historical/snapshot requests over FFI.
+/// Optional builder parameters for registry-driven endpoint requests over FFI.
 ///
 /// Fields use simple C-friendly sentinels:
 ///
@@ -127,9 +127,10 @@ pub struct TdxFpssHandle {
 /// - floating-point values: `NaN` means unset
 /// - string pointers: null means unset
 #[repr(C)]
-pub struct TdxOptionRequestOptions {
+pub struct TdxEndpointRequestOptions {
     pub max_dte: i32,
     pub strike_range: i32,
+    pub venue: *const c_char,
     pub min_time: *const c_char,
     pub start_time: *const c_char,
     pub end_time: *const c_char,
@@ -679,9 +680,9 @@ fn insert_optional_float_arg(args: &mut thetadatadx::EndpointArgs, key: &str, va
     }
 }
 
-fn apply_option_request_options(
+fn apply_endpoint_request_options(
     args: &mut thetadatadx::EndpointArgs,
-    options: *const TdxOptionRequestOptions,
+    options: *const TdxEndpointRequestOptions,
 ) -> Result<(), String> {
     if options.is_null() {
         return Ok(());
@@ -690,6 +691,7 @@ fn apply_option_request_options(
     let options = unsafe { &*options };
     insert_optional_int_arg(args, "max_dte", options.max_dte);
     insert_optional_int_arg(args, "strike_range", options.strike_range);
+    insert_optional_str_arg(args, "venue", options.venue)?;
     insert_optional_str_arg(args, "min_time", options.min_time)?;
     insert_optional_str_arg(args, "start_time", options.start_time)?;
     insert_optional_str_arg(args, "end_time", options.end_time)?;
@@ -1580,8 +1582,8 @@ ffi_typed_endpoint! {
 
 /// Fetch EOD Greeks history with optional builder parameters.
 ///
-/// This currently enables non-Rust bindings to surface parameters such as
-/// `strike_range` without hand-coding Rust builder logic in each language.
+/// This currently enables non-Rust bindings to surface endpoint builder
+/// parameters without hand-coding Rust builder logic in each language.
 #[no_mangle]
 pub unsafe extern "C" fn tdx_option_history_greeks_eod_with_options(
     client: *const TdxClient,
@@ -1591,7 +1593,7 @@ pub unsafe extern "C" fn tdx_option_history_greeks_eod_with_options(
     right: *const c_char,
     start_date: *const c_char,
     end_date: *const c_char,
-    options: *const TdxOptionRequestOptions,
+    options: *const TdxEndpointRequestOptions,
 ) -> TdxGreeksTickArray {
     let empty = TdxGreeksTickArray {
         data: ptr::null(),
@@ -1671,7 +1673,7 @@ pub unsafe extern "C" fn tdx_option_history_greeks_eod_with_options(
         thetadatadx::EndpointArgValue::Str(end_date.to_string()),
     );
 
-    if let Err(message) = apply_option_request_options(&mut args, options) {
+    if let Err(message) = apply_endpoint_request_options(&mut args, options) {
         set_error(&message);
         return empty;
     }

scripts/check_docs_consistency.py

@@ -24,6 +24,12 @@
 ENDPOINT_NAMES = {ep["name"] for ep in ENDPOINTS}
 REST_PATHS = {ep["rest_path"].removeprefix("/v3") for ep in ENDPOINTS}
 EXPECTED_TOOL_COUNT = len(ENDPOINTS) + 3
+BUILDER_PARAMS = {
+    param["name"]
+    for group in SURFACE["param_groups"].values()
+    for param in group.get("params", [])
+    if param.get("binding") == "builder"
+}
 
 
 def lower_camel(snake: str) -> str:
@@ -36,6 +42,14 @@ def fail(message: str) -> None:
     raise SystemExit(1)
 
 
+def snake_to_go(name: str) -> str:
+    acronyms = {
+        "dte": "DTE",
+        "nbbo": "NBBO",
+    }
+    return "".join(acronyms.get(part, part.capitalize()) for part in name.split("_"))
+
+
 def expect_contains(path: Path, snippet: str) -> None:
     text = path.read_text()
     if snippet not in text:
@@ -160,10 +174,93 @@ def check_openapi() -> None:
         )
 
 
+def extract_struct_fields(path: Path, struct_pattern: str, field_pattern: str) -> set[str]:
+    text = path.read_text()
+    match = re.search(struct_pattern, text, re.DOTALL)
+    if not match:
+        fail(f"{path.relative_to(ROOT)} missing expected struct pattern: {struct_pattern!r}")
+    return set(re.findall(field_pattern, match.group(1), re.MULTILINE))
+
+
+def check_endpoint_option_surface() -> None:
+    rust_fields = extract_struct_fields(
+        ROOT / "ffi/src/lib.rs",
+        r"pub struct TdxEndpointRequestOptions \{(.*?)\n\}",
+        r"^\s*pub\s+([a-z_]+)\s*:",
+    )
+    if rust_fields != BUILDER_PARAMS:
+        missing = sorted(BUILDER_PARAMS - rust_fields)
+        extra = sorted(rust_fields - BUILDER_PARAMS)
+        fail(
+            "ffi/src/lib.rs endpoint option fields drifted from endpoint_surface.toml. "
+            f"missing={missing or '[]'} extra={extra or '[]'}"
+        )
+
+    for path in [
+        ROOT / "sdks/go/ffi_bridge.h",
+        ROOT / "sdks/cpp/include/thetadx.h",
+    ]:
+        c_fields = extract_struct_fields(
+            path,
+            r"typedef struct \{(.*?)\n\}\s*TdxEndpointRequestOptions;",
+            r"^\s*(?:const char\*|int32_t|double)\s+([a-z_]+);",
+        )
+        if c_fields != BUILDER_PARAMS:
+            missing = sorted(BUILDER_PARAMS - c_fields)
+            extra = sorted(c_fields - BUILDER_PARAMS)
+            fail(
+                f"{path.relative_to(ROOT)} endpoint option fields drifted from endpoint_surface.toml. "
+                f"missing={missing or '[]'} extra={extra or '[]'}"
+            )
+
+    go_fields = extract_struct_fields(
+        ROOT / "sdks/go/client.go",
+        r"type EndpointRequestOptions struct \{(.*?)\n\}",
+        r"^\s*([A-Z][A-Za-z0-9]+)\s+\*",
+    )
+    expected_go_fields = {snake_to_go(name) for name in BUILDER_PARAMS}
+    if go_fields != expected_go_fields:
+        missing = sorted(expected_go_fields - go_fields)
+        extra = sorted(go_fields - expected_go_fields)
+        fail(
+            "sdks/go/client.go EndpointRequestOptions fields drifted from endpoint_surface.toml. "
+            f"missing={missing or '[]'} extra={extra or '[]'}"
+        )
+
+    cpp_fields = extract_struct_fields(
+        ROOT / "sdks/cpp/include/thetadx.hpp",
+        r"struct EndpointRequestOptions \{(.*?)\n\};",
+        r"^\s*std::optional<[^>]+>\s+([a-z_]+);",
+    )
+    if cpp_fields != BUILDER_PARAMS:
+        missing = sorted(BUILDER_PARAMS - cpp_fields)
+        extra = sorted(cpp_fields - BUILDER_PARAMS)
+        fail(
+            "sdks/cpp/include/thetadx.hpp EndpointRequestOptions fields drifted from endpoint_surface.toml. "
+            f"missing={missing or '[]'} extra={extra or '[]'}"
+        )
+
+    for path in [
+        ROOT / "ffi/src/lib.rs",
+        ROOT / "sdks/go/ffi_bridge.h",
+        ROOT / "sdks/cpp/include/thetadx.h",
+        ROOT / "sdks/go/client.go",
+        ROOT / "sdks/cpp/include/thetadx.hpp",
+        ROOT / "sdks/cpp/src/thetadx.cpp",
+        ROOT / "sdks/go/README.md",
+        ROOT / "sdks/cpp/README.md",
+        ROOT / "docs-site/docs/getting-started/migration-from-rest-ws.md",
+        ROOT / "docs-site/docs/historical/option/history/greeks-eod.md",
+    ]:
+        expect_not_contains(path, "OptionRequestOptions")
+        expect_not_contains(path, "TdxOptionRequestOptions")
+
+
 def main() -> None:
     check_static_docs()
     check_api_reference()
     check_openapi()
+    check_endpoint_option_surface()
     print("docs consistency: ok")
 
 

sdks/cpp/README.md

@@ -165,7 +165,7 @@ auto client = tdx::Client::connect(creds, tdx::Config::production());
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `option_history_greeks_eod(sym, exp, strike, right, start, end[, options])` | `vector<GreeksTick>` | EOD Greeks history. Optional `OptionRequestOptions` exposes filters such as `strike_range`. |
+| `option_history_greeks_eod(sym, exp, strike, right, start, end[, options])` | `vector<GreeksTick>` | EOD Greeks history. Optional `EndpointRequestOptions` exposes filters such as `strike_range`. |
 | `option_history_greeks_all(sym, exp, strike, right, date, interval)` | `vector<GreeksTick>` | All Greeks history (intraday) |
 | `option_history_trade_greeks_all(sym, exp, strike, right, date)` | `vector<GreeksTick>` | All Greeks on each trade |
 | `option_history_greeks_first_order(sym, exp, strike, right, date, interval)` | `vector<GreeksTick>` | First-order Greeks history |

sdks/cpp/include/thetadx.h

@@ -39,7 +39,7 @@ typedef struct TdxConfig TdxConfig;
 typedef struct TdxFpssHandle TdxFpssHandle;
 typedef struct TdxUnified TdxUnified;
 
-/* Optional builder parameters for option historical/snapshot requests.
+/* Optional builder parameters for registry-driven endpoint requests.
  * Sentinels:
  * - integers: -1 means unset
  * - booleans: -1 unset, 0 false, 1 true
@@ -49,6 +49,7 @@ typedef struct TdxUnified TdxUnified;
 typedef struct {
     int32_t max_dte;
     int32_t strike_range;
+    const char* venue;
     const char* min_time;
     const char* start_time;
     const char* end_time;
@@ -62,7 +63,7 @@ typedef struct {
     const char* version;
     int32_t underlyer_use_nbbo;
     int32_t use_market_value;
-} TdxOptionRequestOptions;
+} TdxEndpointRequestOptions;
 
 /* ═══════════════════════════════════════════════════════════════════════ */
 /*  #[repr(C)] tick types — layout-compatible with Rust tdbe structs      */
@@ -625,7 +626,7 @@ TdxGreeksTickArray tdx_option_history_greeks_eod(const TdxClient* client, const
 TdxGreeksTickArray tdx_option_history_greeks_eod_with_options(const TdxClient* client, const char* symbol, const char* expiration,
                                                               const char* strike, const char* right,
                                                               const char* start_date, const char* end_date,
-                                                              const TdxOptionRequestOptions* options);
+                                                              const TdxEndpointRequestOptions* options);
 
 TdxGreeksTickArray tdx_option_history_greeks_all(const TdxClient* client, const char* symbol, const char* expiration,
                                                   const char* strike, const char* right,

sdks/cpp/include/thetadx.hpp

@@ -83,16 +83,25 @@ struct Greeks {
     double lambda;
 };
 
-/// Optional builder parameters for option historical/snapshot requests.
+/// Optional builder parameters for registry-driven endpoint wrappers.
 ///
-/// The C++ wrapper uses `std::optional` so callers can opt into the same
-/// metadata-driven filters exposed by Rust without sentinel values.
-struct OptionRequestOptions {
+/// Rust models these as builder setters. The C++ wrapper projects the same
+/// surface as a value object with `std::optional` fields.
+struct EndpointRequestOptions {
+    std::optional<std::string> venue;
+    std::optional<std::string> min_time;
+    std::optional<std::string> start_time;
+    std::optional<std::string> end_time;
+    std::optional<std::string> start_date;
+    std::optional<std::string> end_date;
+    std::optional<bool> exclusive;
     std::optional<double> annual_dividend;
     std::optional<std::string> rate_type;
     std::optional<double> rate_value;
+    std::optional<double> stock_price;
     std::optional<std::string> version;
     std::optional<bool> underlyer_use_nbbo;
+    std::optional<bool> use_market_value;
     std::optional<int32_t> max_dte;
     std::optional<int32_t> strike_range;
 };
@@ -391,7 +400,7 @@ class Client {
     std::vector<GreeksTick> option_history_greeks_eod(const std::string& symbol, const std::string& expiration,
                                                       const std::string& strike, const std::string& right,
                                                       const std::string& start_date, const std::string& end_date,
-                                                      const OptionRequestOptions& options = {}) const;
+                                                      const EndpointRequestOptions& options = {}) const;
     std::vector<GreeksTick> option_history_greeks_all(const std::string& symbol, const std::string& expiration,
                                                       const std::string& strike, const std::string& right,
                                                       const std::string& date, const std::string& interval) const;