v0.4.0-rc.1: ExposureSummary typed POCO + 100% field-coverage integration test

- Add ExposureSummaryResponse + 5 sub-types mirroring the existing
  ZeroDteResponse pattern. Field-level Optional/nullable across all five
  languages.
- Wire the new types into the package root export.
- Integration test now references every leaf field declared in the POCO.
- Bump version to 0.4.0-rc.1 (PEP 440: 0.4.0rc1; npm/NuGet: 0.4.0-rc.1;
  Maven: 0.4.0-RC1).

API behaviour clarifications confirmed via live probe:
- regime ∈ {positive_gamma, negative_gamma, neutral, undetermined}
  (`neutral` is not in the API doc text but appears in live responses
  when net_gex straddles zero; existing tests already accepted it).
- direction on both /exposure/summary and /exposure/zero-dte is
  lowercase "buy"/"sell". Existing API docs show uppercase BUY/SELL on
  summary but the live response is lowercase. Type definitions reflect
  the actual response, not the docs.

Backwards-compatible: existing untyped methods continue to return raw
JsonElement / map[string]interface{} / dict / unknown unchanged. Typed
return-type annotations on Python/TS are non-breaking (TypedDict /
interface).

Author: tdobrowolski1

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "0.3.7"
+version = "0.4.0rc1"
 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"
@@ -57,7 +57,7 @@ classifiers = [
     "Topic :: Office/Business :: Financial :: Investment",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-dependencies = ["requests>=2.28"]
+dependencies = ["requests>=2.33.0"]
 
 [project.urls]
 Homepage = "https://flashalpha.com"

src/flashalpha/__init__.py

@@ -10,6 +10,12 @@
     TierRestrictedError,
 )
 from .types import (
+    ExposureSummaryExposures,
+    ExposureSummaryHedgingEstimate,
+    ExposureSummaryHedgingMove,
+    ExposureSummaryInterpretation,
+    ExposureSummaryResponse,
+    ExposureSummaryZeroDte,
     ZeroDteDecay,
     ZeroDteExpectedMove,
     ZeroDteExposures,
@@ -27,7 +33,7 @@
     ZeroDteVolContext,
 )
 
-__version__ = "0.3.7"
+__version__ = "0.4.0rc1"
 __all__ = [
     "FlashAlpha",
     "FlashAlphaError",
@@ -51,4 +57,11 @@
     "ZeroDteLiquidity",
     "ZeroDteMetadata",
     "ZeroDteStrike",
+    # ── ExposureSummary ──
+    "ExposureSummaryResponse",
+    "ExposureSummaryExposures",
+    "ExposureSummaryInterpretation",
+    "ExposureSummaryHedgingEstimate",
+    "ExposureSummaryHedgingMove",
+    "ExposureSummaryZeroDte",
 ]

src/flashalpha/types.py

@@ -213,3 +213,62 @@ class ZeroDteResponse(TypedDict, total=False):
     no_zero_dte: bool
     message: str
     next_zero_dte_expiry: Optional[str]
+
+
+# ─── ExposureSummary ─────────────────────────────────────────────────────────
+#
+# Typed model for ``GET /v1/exposure/summary/{symbol}``.
+#
+# Direction casing: /v1/exposure/summary/ and /v1/exposure/zero-dte/ both
+# return lowercase "buy" / "sell". Docs and typed models use that casing
+# consistently.
+
+
+class ExposureSummaryExposures(TypedDict, total=False):
+    # Field-level Optional matches C#/Go/Java (defensive — API may return null
+    # under unobserved edge conditions even when the parent block is present).
+    net_gex: Optional[float]
+    net_dex: Optional[float]
+    net_vex: Optional[float]
+    net_chex: Optional[float]
+
+
+class ExposureSummaryInterpretation(TypedDict, total=False):
+    gamma: Optional[str]
+    vanna: Optional[str]
+    charm: Optional[str]
+
+
+class ExposureSummaryHedgingMove(TypedDict, total=False):
+    dealer_shares_to_trade: Optional[float]
+    direction: Optional[Literal["buy", "sell"]]
+    notional_usd: Optional[float]
+
+
+class ExposureSummaryHedgingEstimate(TypedDict, total=False):
+    spot_up_1pct: ExposureSummaryHedgingMove
+    spot_down_1pct: ExposureSummaryHedgingMove
+
+
+class ExposureSummaryZeroDte(TypedDict, total=False):
+    net_gex: Optional[float]
+    pct_of_total_gex: Optional[float]
+    expiration: Optional[str]
+
+
+class ExposureSummaryResponse(TypedDict, total=False):
+    symbol: str
+    underlying_price: Optional[float]
+    as_of: str
+    gamma_flip: Optional[float]
+    # Confirmed live values in tests across Py/JS/.NET/Go/Java:
+    #   positive_gamma | negative_gamma | neutral
+    # Documented fourth value: undetermined (when there's no usable options
+    # data). `neutral` appears in edge cases where net_gex straddles zero.
+    # Don't conflate with ``maxpain.signal`` (also bullish/bearish/neutral but
+    # a separate field).
+    regime: Literal["positive_gamma", "negative_gamma", "neutral", "undetermined"]
+    exposures: ExposureSummaryExposures
+    interpretation: ExposureSummaryInterpretation
+    hedging_estimate: ExposureSummaryHedgingEstimate
+    zero_dte: ExposureSummaryZeroDte

tests/test_integration.py

@@ -113,10 +113,40 @@ def test_exposure_levels(fa):
 
 
 def test_exposure_summary(fa):
+    """Every field declared in ExposureSummaryResponse must be referenced."""
     result = fa.exposure_summary("SPY")
+    # ── top-level scalars ──
     assert result["symbol"] == "SPY"
-    assert "exposures" in result
-    assert "regime" in result
+    assert "underlying_price" in result and isinstance(result["underlying_price"], (int, float))
+    assert isinstance(result["as_of"], str) and result["as_of"]
+    assert isinstance(result["gamma_flip"], (int, float))
+    assert result["regime"] in ("positive_gamma", "negative_gamma", "neutral", "undetermined")
+    # ── exposures block (4 fields) ──
+    e = result["exposures"]
+    for k in ("net_gex", "net_dex", "net_vex", "net_chex"):
+        assert isinstance(e[k], (int, float)), f"exposures.{k}"
+    # ── interpretation block (3 fields) ──
+    interp = result["interpretation"]
+    for k in ("gamma", "vanna", "charm"):
+        assert isinstance(interp[k], str) and interp[k], f"interpretation.{k}"
+    # ── hedging_estimate (every leaf field on both sides) ──
+    h = result["hedging_estimate"]
+    up, down = h["spot_up_1pct"], h["spot_down_1pct"]
+    for side in (up, down):
+        # Both summary + zero-dte return lowercase.
+        assert side["direction"] in ("buy", "sell")
+        assert isinstance(side["dealer_shares_to_trade"], (int, float))
+        assert isinstance(side["notional_usd"], (int, float))
+        assert side["notional_usd"] != 0
+    assert up["dealer_shares_to_trade"] == -down["dealer_shares_to_trade"]
+    # ── zero_dte block (3 fields) ──
+    z = result["zero_dte"]
+    assert isinstance(z, dict)
+    assert "net_gex" in z and (z["net_gex"] is None or isinstance(z["net_gex"], (int, float)))
+    assert "pct_of_total_gex" in z and (
+        z["pct_of_total_gex"] is None or isinstance(z["pct_of_total_gex"], (int, float))
+    )
+    assert "expiration" in z and (z["expiration"] is None or isinstance(z["expiration"], str))
 
 
 def test_narrative(fa):