v0.3.4: typed ZeroDteResponse models + comprehensive typed integration test

Add a strongly-typed mirror of the GET /v1/exposure/zero-dte/{symbol} response.
The new types live in flashalpha.types as a TypedDict tree (runtime-equal to
plain dict — fully backward-compatible with existing dict-style access).

- ZeroDteResponse covers all 145 documented fields including the new
  liquidity and metadata sections, hedging fine-grained buckets
  (10bp/25bp/half_pct), pin_risk component sub-scores, level cluster score,
  per-strike greeks/quotes/spreads, and the conditional warnings array.
- zero_dte() return annotation tightened from `dict` to `ZeroDteResponse`.
  No runtime change — TypedDict is dict at runtime.
- Re-export all type aliases from flashalpha.__init__ for convenient import.
- Add test_zero_dte_typed_response — comprehensive end-to-end check that
  every documented field is populated when accessed via the typed paths.

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

Author: tdobrowolski1

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "0.3.3"
+version = "0.3.4"
 description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
 readme = "README.md"
 license = "MIT"

src/flashalpha/__init__.py

@@ -9,8 +9,25 @@
     ServerError,
     TierRestrictedError,
 )
+from .types import (
+    ZeroDteDecay,
+    ZeroDteExpectedMove,
+    ZeroDteExposures,
+    ZeroDteFlow,
+    ZeroDteHedging,
+    ZeroDteHedgingBucket,
+    ZeroDteLevels,
+    ZeroDteLiquidity,
+    ZeroDteMetadata,
+    ZeroDtePinComponents,
+    ZeroDtePinRisk,
+    ZeroDteRegime,
+    ZeroDteResponse,
+    ZeroDteStrike,
+    ZeroDteVolContext,
+)
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 __all__ = [
     "FlashAlpha",
     "FlashAlphaError",
@@ -19,4 +36,19 @@
     "NotFoundError",
     "RateLimitError",
     "ServerError",
+    "ZeroDteResponse",
+    "ZeroDteRegime",
+    "ZeroDteExposures",
+    "ZeroDteExpectedMove",
+    "ZeroDtePinRisk",
+    "ZeroDtePinComponents",
+    "ZeroDteHedging",
+    "ZeroDteHedgingBucket",
+    "ZeroDteDecay",
+    "ZeroDteVolContext",
+    "ZeroDteFlow",
+    "ZeroDteLevels",
+    "ZeroDteLiquidity",
+    "ZeroDteMetadata",
+    "ZeroDteStrike",
 ]

src/flashalpha/client.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import requests
 
@@ -15,6 +15,9 @@
     TierRestrictedError,
 )
 
+if TYPE_CHECKING:
+    from .types import ZeroDteResponse
+
 BASE_URL = "https://lab.flashalpha.com"
 
 
@@ -192,8 +195,13 @@ def narrative(self, symbol: str) -> dict:
         """Verbal narrative analysis of exposure. Requires Growth+."""
         return self._get(f"/v1/exposure/narrative/{symbol}")
 
-    def zero_dte(self, symbol: str, *, strike_range: float | None = None) -> dict:
-        """Real-time 0DTE analytics: regime, expected move, pin risk, hedging, decay. Requires Growth+."""
+    def zero_dte(self, symbol: str, *, strike_range: float | None = None) -> "ZeroDteResponse":
+        """Real-time 0DTE analytics: regime, expected move, pin risk, hedging, decay. Requires Growth+.
+
+        Returns a ``ZeroDteResponse`` (a ``TypedDict`` — runtime-equivalent to
+        ``dict``). Existing ``result["field"]`` access continues to work; new
+        callers get autocomplete and type-checking on the documented fields.
+        """
         params: dict[str, Any] = {}
         if strike_range is not None:
             params["strike_range"] = strike_range

src/flashalpha/types.py

@@ -0,0 +1,215 @@
+"""Typed response models for FlashAlpha SDK.
+
+These are ``TypedDict`` aliases — at runtime each is a plain ``dict``. Existing
+code that does ``result["field"]`` keeps working unchanged. Static type
+checkers (mypy/pyright) and IDEs see the field shape and provide autocomplete.
+
+Currently typed:
+    - ``ZeroDteResponse`` (full payload of GET /v1/exposure/zero-dte/{symbol})
+
+All numeric fields are typed ``Optional[float]``/``Optional[int]`` because
+the API returns ``null`` for any value it can't compute (insufficient data,
+market closed, etc.). Treat the typed shape as a *hint*, not a guarantee —
+unknown fields added by the API in future revisions will still pass through.
+"""
+
+from typing import List, Literal, Optional, TypedDict
+
+
+class ZeroDteRegime(TypedDict, total=False):
+    label: str
+    description: str
+    gamma_flip: Optional[float]
+    spot_vs_flip: Literal["above", "below"]
+    spot_to_flip_pct: Optional[float]
+    distance_to_flip_dollars: Optional[float]
+    distance_to_flip_sigmas: Optional[float]
+
+
+class ZeroDteExposures(TypedDict, total=False):
+    net_gex: float
+    net_dex: float
+    net_vex: float
+    net_chex: float
+    pct_of_total_gex: Optional[float]
+    total_chain_net_gex: float
+
+
+class ZeroDteExpectedMove(TypedDict, total=False):
+    implied_1sd_dollars: Optional[float]
+    implied_1sd_pct: Optional[float]
+    remaining_1sd_dollars: Optional[float]
+    remaining_1sd_pct: Optional[float]
+    upper_bound: Optional[float]
+    lower_bound: Optional[float]
+    straddle_price: Optional[float]
+    atm_iv: Optional[float]
+
+
+class ZeroDtePinComponents(TypedDict, total=False):
+    oi_score: int
+    proximity_score: int
+    time_score: int
+    gamma_score: int
+
+
+class ZeroDtePinRisk(TypedDict, total=False):
+    magnet_strike: Optional[float]
+    magnet_gex: Optional[float]
+    distance_to_magnet_pct: Optional[float]
+    pin_score: int
+    components: ZeroDtePinComponents
+    max_pain: Optional[float]
+    oi_concentration_top3_pct: Optional[float]
+    description: str
+
+
+class ZeroDteHedgingBucket(TypedDict, total=False):
+    dealer_shares_to_trade: float
+    direction: Literal["buy", "sell"]
+    notional_usd: float
+
+
+class ZeroDteHedging(TypedDict, total=False):
+    spot_up_10bp: ZeroDteHedgingBucket
+    spot_down_10bp: ZeroDteHedgingBucket
+    spot_up_25bp: ZeroDteHedgingBucket
+    spot_down_25bp: ZeroDteHedgingBucket
+    spot_up_half_pct: ZeroDteHedgingBucket
+    spot_down_half_pct: ZeroDteHedgingBucket
+    spot_up_1pct: ZeroDteHedgingBucket
+    spot_down_1pct: ZeroDteHedgingBucket
+    convexity_at_spot: Optional[float]
+
+
+class ZeroDteDecay(TypedDict, total=False):
+    net_theta_dollars: Optional[float]
+    theta_per_hour_remaining: Optional[float]
+    charm_regime: str
+    charm_description: str
+    gamma_acceleration: Optional[float]
+    description: str
+
+
+class ZeroDteVolContext(TypedDict, total=False):
+    zero_dte_atm_iv: Optional[float]
+    seven_dte_atm_iv: Optional[float]
+    iv_ratio_0dte_7dte: Optional[float]
+    vix: Optional[float]
+    vanna_exposure: Optional[float]
+    vanna_interpretation: str
+    description: str
+
+
+class ZeroDteFlow(TypedDict, total=False):
+    total_volume: int
+    call_volume: int
+    put_volume: int
+    net_call_minus_put_volume: int
+    total_oi: int
+    call_oi: int
+    put_oi: int
+    pc_ratio_volume: Optional[float]
+    pc_ratio_oi: Optional[float]
+    volume_to_oi_ratio: Optional[float]
+    atm_volume_share_pct: Optional[float]
+    top3_strike_volume_pct: Optional[float]
+
+
+class ZeroDteLevels(TypedDict, total=False):
+    call_wall: Optional[float]
+    call_wall_gex: Optional[float]
+    call_wall_strength: Optional[float]
+    distance_to_call_wall_pct: Optional[float]
+    put_wall: Optional[float]
+    put_wall_gex: Optional[float]
+    put_wall_strength: Optional[float]
+    distance_to_put_wall_pct: Optional[float]
+    distance_to_magnet_dollars: Optional[float]
+    highest_oi_strike: Optional[float]
+    highest_oi_total: Optional[int]
+    max_positive_gamma: Optional[float]
+    max_negative_gamma: Optional[float]
+    level_cluster_score: Optional[int]
+
+
+class ZeroDteLiquidity(TypedDict, total=False):
+    atm_spread_pct: Optional[float]
+    weighted_spread_pct: Optional[float]
+    execution_score: Optional[int]
+
+
+class ZeroDteMetadata(TypedDict, total=False):
+    snapshot_age_seconds: Optional[float]
+    chain_contract_count: int
+    data_quality_score: Optional[int]
+    greek_smoothness_score: Optional[int]
+
+
+class ZeroDteStrike(TypedDict, total=False):
+    strike: float
+    distance_from_spot_pct: float
+    call_symbol: str
+    put_symbol: str
+    call_gex: Optional[float]
+    put_gex: Optional[float]
+    net_gex: Optional[float]
+    call_dex: Optional[float]
+    put_dex: Optional[float]
+    net_dex: Optional[float]
+    net_vex: Optional[float]
+    net_chex: Optional[float]
+    call_oi: Optional[int]
+    put_oi: Optional[int]
+    call_volume: Optional[int]
+    put_volume: Optional[int]
+    gex_share_pct: Optional[float]
+    oi_share_pct: Optional[float]
+    volume_share_pct: Optional[float]
+    call_iv: Optional[float]
+    put_iv: Optional[float]
+    call_delta: Optional[float]
+    put_delta: Optional[float]
+    call_gamma: Optional[float]
+    put_gamma: Optional[float]
+    call_theta: Optional[float]
+    put_theta: Optional[float]
+    call_mid: Optional[float]
+    put_mid: Optional[float]
+    call_spread_pct: Optional[float]
+    put_spread_pct: Optional[float]
+
+
+class ZeroDteResponse(TypedDict, total=False):
+    """Full response for GET /v1/exposure/zero-dte/{symbol}.
+
+    On weekends/holidays or symbols without 0DTE today, ``no_zero_dte`` is
+    ``True`` and most fields are absent — only ``symbol``, ``as_of``,
+    ``message``, and ``next_zero_dte_expiry`` are populated.
+    """
+
+    symbol: str
+    underlying_price: float
+    expiration: Optional[str]
+    as_of: str
+    market_open: bool
+    time_to_close_hours: Optional[float]
+    time_to_close_pct: Optional[float]
+    regime: ZeroDteRegime
+    exposures: ZeroDteExposures
+    expected_move: ZeroDteExpectedMove
+    pin_risk: ZeroDtePinRisk
+    hedging: ZeroDteHedging
+    decay: ZeroDteDecay
+    vol_context: ZeroDteVolContext
+    flow: ZeroDteFlow
+    levels: ZeroDteLevels
+    liquidity: ZeroDteLiquidity
+    metadata: ZeroDteMetadata
+    strikes: List[ZeroDteStrike]
+    # Optional — only present near close (<5 min) when greeks may be unstable.
+    warnings: List[str]
+    # ── No-0DTE fallback ─────────────────────────────────────────────
+    no_zero_dte: bool
+    message: str
+    next_zero_dte_expiry: Optional[str]