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

- Add ExposureSummaryResponse + 5 sub-types (ExposureSummaryExposures,
  ExposureSummaryInterpretation, ExposureSummaryHedgingMove,
  ExposureSummaryHedgingEstimate, ExposureSummaryZeroDte) mirroring the
  live SDK's pattern (ZeroDteResponse). Field-level nullability aligned
  with C#/Go/Java defensive convention.
- 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 confirmed via live + historical probes:
- regime ∈ {positive_gamma, negative_gamma, neutral, undetermined}
  (`neutral` was previously missing from the type set).
- direction is lowercase "buy"/"sell" on BOTH summary and zero-dte
  (live API doc shows uppercase but actual response is lowercase).
- as_of_requested exists on /exposure/{gex,dex,narrative} but NOT on
  /exposure/summary; removed from this type.

Author: tdobrowolski1

src/FlashAlpha.Historical/FlashAlpha.Historical.csproj

@@ -9,7 +9,7 @@
     <RootNamespace>FlashAlpha.Historical</RootNamespace>
 
     <PackageId>FlashAlpha.Historical</PackageId>
-    <Version>0.1.0</Version>
+    <Version>0.4.0-rc.1</Version>
     <Authors>FlashAlpha</Authors>
     <Company>FlashAlpha</Company>
     <Description>Official .NET SDK for the FlashAlpha Historical API — point-in-time replay of GEX, gamma flip, VRP, narrative, max pain, 0DTE, and the full stock summary at any minute back to 2018-04-16. Backtest options strategies against 6.7B+ option rows.</Description>

src/FlashAlpha.Historical/Models/ExposureSummary.cs

@@ -0,0 +1,123 @@
+using System.Text.Json.Serialization;
+
+namespace FlashAlpha.Historical.Models;
+
+/// <summary>
+/// Typed response model for <c>GET /v1/exposure/summary/{symbol}?at=...</c>.
+///
+/// <para>The Historical API returns the same response shape as the live API;
+/// the only difference is every analytics endpoint requires an <c>at</c> query
+/// parameter (string or <see cref="System.DateTime"/>).</para>
+///
+/// <para><b>Direction casing:</b> confirmed via live probe — both
+/// <c>/v1/exposure/summary/</c> and <c>/v1/exposure/zero-dte/</c> return
+/// lowercase <c>"buy"</c>/<c>"sell"</c>. Casing is consistent across
+/// summary and zero-DTE endpoints.</para>
+/// </summary>
+public sealed class ExposureSummaryResponse
+{
+    [JsonPropertyName("symbol")]
+    public string? Symbol { get; set; }
+
+    [JsonPropertyName("underlying_price")]
+    public double? UnderlyingPrice { get; set; }
+
+    /// <summary>The as-of stamp the API actually used (snapped to the available minute).</summary>
+    [JsonPropertyName("as_of")]
+    public string? AsOf { get; set; }
+
+    // Note: as_of_requested exists on /v1/exposure/{gex,dex,narrative} but
+    // NOT on /v1/exposure/summary. Don't add it to this type even though it
+    // would be defensive — the field genuinely isn't returned for this endpoint.
+
+    [JsonPropertyName("gamma_flip")]
+    public double? GammaFlip { get; set; }
+
+    /// <summary>
+    /// One of <c>"positive_gamma"</c>, <c>"negative_gamma"</c>,
+    /// <c>"neutral"</c>, or <c>"undetermined"</c>.
+    /// </summary>
+    [JsonPropertyName("regime")]
+    public string? Regime { get; set; }
+
+    [JsonPropertyName("exposures")]
+    public ExposureSummaryExposures? Exposures { get; set; }
+
+    [JsonPropertyName("interpretation")]
+    public ExposureSummaryInterpretation? Interpretation { get; set; }
+
+    [JsonPropertyName("hedging_estimate")]
+    public ExposureSummaryHedgingEstimate? HedgingEstimate { get; set; }
+
+    [JsonPropertyName("zero_dte")]
+    public ExposureSummaryZeroDte? ZeroDte { get; set; }
+}
+
+/// <summary>Net exposure totals across the entire chain.</summary>
+public sealed class ExposureSummaryExposures
+{
+    [JsonPropertyName("net_gex")]
+    public double? NetGex { get; set; }
+
+    [JsonPropertyName("net_dex")]
+    public double? NetDex { get; set; }
+
+    [JsonPropertyName("net_vex")]
+    public double? NetVex { get; set; }
+
+    [JsonPropertyName("net_chex")]
+    public double? NetChex { get; set; }
+}
+
+/// <summary>Verbal interpretation of the gamma/vanna/charm regimes.</summary>
+public sealed class ExposureSummaryInterpretation
+{
+    [JsonPropertyName("gamma")]
+    public string? Gamma { get; set; }
+
+    [JsonPropertyName("vanna")]
+    public string? Vanna { get; set; }
+
+    [JsonPropertyName("charm")]
+    public string? Charm { get; set; }
+}
+
+/// <summary>One side (up or down) of a dealer-hedging estimate.</summary>
+public sealed class ExposureSummaryHedgingMove
+{
+    [JsonPropertyName("dealer_shares_to_trade")]
+    public double? DealerSharesToTrade { get; set; }
+
+    /// <summary>
+    /// <c>"buy"</c> or <c>"sell"</c> (lowercase on both this endpoint and
+    /// zero-dte).
+    /// </summary>
+    [JsonPropertyName("direction")]
+    public string? Direction { get; set; }
+
+    [JsonPropertyName("notional_usd")]
+    public double? NotionalUsd { get; set; }
+}
+
+/// <summary>Estimated dealer hedging flow at +/- 1% spot moves.</summary>
+public sealed class ExposureSummaryHedgingEstimate
+{
+    [JsonPropertyName("spot_up_1pct")]
+    public ExposureSummaryHedgingMove? SpotUp1Pct { get; set; }
+
+    [JsonPropertyName("spot_down_1pct")]
+    public ExposureSummaryHedgingMove? SpotDown1Pct { get; set; }
+}
+
+/// <summary>Same-day-expiration contribution to total GEX.</summary>
+public sealed class ExposureSummaryZeroDte
+{
+    [JsonPropertyName("net_gex")]
+    public double? NetGex { get; set; }
+
+    [JsonPropertyName("pct_of_total_gex")]
+    public double? PctOfTotalGex { get; set; }
+
+    [JsonPropertyName("expiration")]
+    public string? Expiration { get; set; }
+}

tests/FlashAlpha.Historical.Tests/IntegrationTests.cs

@@ -21,7 +21,7 @@ public class IntegrationTests
     private const double SpotTol = 1.0;
 
     private static readonly HashSet<string> Regimes =
-        new() { "positive_gamma", "negative_gamma", "transition" };
+        new() { "positive_gamma", "negative_gamma", "neutral", "undetermined" };
 
     private static readonly string? ApiKey = Environment.GetEnvironmentVariable("FLASHALPHA_API_KEY");
 
@@ -125,22 +125,51 @@ public async Task OptionQuote_AllFilters_ReturnsSingleObjectWithGreeks()
     // ── Exposure ───────────────────────────────────────────────────────────
 
     [SkippableFact]
-    public async Task ExposureSummary_ShapeAndInvariants()
+    public async Task ExposureSummary_EveryFieldDeclaredInPocoMustBeReferenced()
     {
         Skip.IfNot(HasKey, SkipReason);
         using var client = MakeClient();
         var s = await client.ExposureSummaryAsync("SPY", SpyAt);
+        // ── top-level scalars ──
         Assert.Equal("SPY", s.GetProperty("symbol").GetString());
         Assert.True(Math.Abs(s.GetProperty("underlying_price").GetDouble() - ExpectedSpot) < SpotTol);
+        Assert.Equal(JsonValueKind.String, s.GetProperty("as_of").ValueKind);
+        Assert.False(string.IsNullOrEmpty(s.GetProperty("as_of").GetString()));
+        Assert.Equal(SpyAt, s.GetProperty("as_of").GetString()); // historical snaps to requested minute
         Assert.Contains(s.GetProperty("regime").GetString()!, Regimes);
         Assert.Equal(JsonValueKind.Number, s.GetProperty("gamma_flip").ValueKind);
+        // ── exposures block (4 fields) ──
         var e = s.GetProperty("exposures");
         foreach (var k in new[] { "net_gex", "net_dex", "net_vex", "net_chex" })
             Assert.Equal(JsonValueKind.Number, e.GetProperty(k).ValueKind);
+        // ── interpretation block (3 fields) ──
+        var interp = s.GetProperty("interpretation");
+        foreach (var k in new[] { "gamma", "vanna", "charm" })
+        {
+            Assert.Equal(JsonValueKind.String, interp.GetProperty(k).ValueKind);
+            Assert.False(string.IsNullOrEmpty(interp.GetProperty(k).GetString()));
+        }
+        // ── hedging_estimate (every leaf on both sides) ──
         var h = s.GetProperty("hedging_estimate");
+        foreach (var sideKey in new[] { "spot_up_1pct", "spot_down_1pct" })
+        {
+            var side = h.GetProperty(sideKey);
+            Assert.Contains(side.GetProperty("direction").GetString(), new[] { "buy", "sell" });
+            Assert.Equal(JsonValueKind.Number, side.GetProperty("dealer_shares_to_trade").ValueKind);
+            Assert.Equal(JsonValueKind.Number, side.GetProperty("notional_usd").ValueKind);
+            Assert.NotEqual(0, side.GetProperty("notional_usd").GetInt64());
+        }
         var up = h.GetProperty("spot_up_1pct").GetProperty("dealer_shares_to_trade").GetInt64();
         var down = h.GetProperty("spot_down_1pct").GetProperty("dealer_shares_to_trade").GetInt64();
         Assert.Equal(up, -down);
+        // ── zero_dte block (3 fields) ──
+        var z = s.GetProperty("zero_dte");
+        Assert.True(z.TryGetProperty("net_gex", out var zng));
+        Assert.True(zng.ValueKind == JsonValueKind.Null || zng.ValueKind == JsonValueKind.Number);
+        Assert.True(z.TryGetProperty("pct_of_total_gex", out var zpct));
+        Assert.True(zpct.ValueKind == JsonValueKind.Null || zpct.ValueKind == JsonValueKind.Number);
+        Assert.True(z.TryGetProperty("expiration", out var zexp));
+        Assert.True(zexp.ValueKind == JsonValueKind.Null || zexp.ValueKind == JsonValueKind.String);
     }
 
     [SkippableFact]