feat: add Special Situations SDK workflows

README.md

@@ -10,6 +10,7 @@ Bootstrap async Rust client for SEC API factor data, filings, statements, owners
 - factor catalog, returns, history, valuations, exposures, decomposition, pairs, and custom discovery
 - portfolio factor attribution, hedging, optimization, stress testing, and model factor analysis
 - offerings, market calendar, and volatility signal utilities
+- Special Situations list/detail/feed/calendar/stats/performance, underwriting-pack JSON, Copy-for-LLM markdown exports, and weekly issue archive reads
 - MCP info discovery and hosted tool calls
 
 ## Example
@@ -136,9 +137,82 @@ let history = client
 ```
 
 Start with `client.entities()`, `client.filings()`, `client.sections()`,
-`client.search()`, and `client.factors()` when exploring. The grouped services
-borrow the client and delegate to the flat methods, so auth, retries, timeouts,
-and custom HTTP clients behave exactly the same.
+`client.search()`, `client.factors()`, and `client.situations()` when exploring.
+The grouped services borrow the client and delegate to the flat methods, so
+auth, retries, timeouts, and custom HTTP clients behave exactly the same.
+
+## Special Situations
+
+The public Special Situations surface exposes SEC-derived situations only:
+durable public-company events such as M&A, tender offers, going-private
+transactions, spin-offs, activist campaigns, restructurings, and bankruptcy
+processes. The methods below map only to documented public endpoints.
+
+```rust
+use sec_api_sdk_rust::SecApiClient;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = SecApiClient::new(std::env::var("SECAPI_API_KEY").ok());
+
+    let situations = client
+        .situations()
+        .list(&[("types", "ma,tender_offer"), ("limit", "10"), ("response_mode", "agent")])
+        .await?;
+
+    let first_id = situations["data"][0]["id"].as_str().unwrap_or_default();
+    let detail = client.situations().get(first_id, &[("enrich", "false")]).await?;
+    let filings = client.situations().filings(first_id, &[("limit", "25")]).await?;
+    let summary = client.situations().summary(first_id, &[]).await?;
+    let underwriting = client.situations().underwriting_pack(first_id).await?;
+    let markdown = client.situations().copy_for_llm(first_id, &[]).await?;
+
+    println!(
+        "{} {} {} {} {}",
+        detail["headline"],
+        filings["data"].as_array().map_or(0, Vec::len),
+        summary["summaryMd"],
+        underwriting["id"],
+        markdown
+    );
+
+    Ok(())
+}
+```
+
+Other grouped helpers map directly to the public REST routes:
+
+```rust
+let feed = client.situations().feed(&[("types", "ma"), ("limit", "25")]).await?;
+let calendar = client.situations().calendar(&[("days", "90")]).await?;
+let stats = client.situations().stats(&[("window", "30d")]).await?;
+let performance = client.situations().performance(&[("group_by", "subtype")]).await?;
+let by_form = client.situations().by_form("SC TO-T", &[("limit", "10")]).await?;
+let underwriting = client.situations().underwriting_pack("sit_123").await?;
+let flat_underwriting = client.situation_underwriting_pack("sit_123").await?;
+```
+
+`underwriting_pack(...)` and `situation_underwriting_pack(...)` call
+`GET /v1/situations/{id}/underwriting-pack` with no query parameters and return
+the raw JSON response as `serde_json::Value`. The pack is limited to public
+Special Situations data derived from SEC sources; it does not expose internal or
+TIKR data.
+
+Weekly issue archive helpers are also available:
+
+```rust
+let issues = client.situations().issues(&[("limit", "12")]).await?;
+let issue = client.situations().issue("22", &[]).await?;
+```
+
+Archive issue endpoints (`GET /v1/situations/issues` and
+`GET /v1/situations/issues/{issue}`) and the underwriting-pack endpoint
+(`GET /v1/situations/{id}/underwriting-pack`) intentionally depend on
+datastream PR
+[#1363](https://github.com/autonomous-computer/omni-datastream/pull/1363).
+Until that PR is merged and deployed to the API origin you call, these helpers
+may return the API's normal not-found or unavailable response even though the
+SDK methods compile.
 
 ## Auto-pagination