⚠️ EXPERIMENTAL: Authentication and session management for Yahoo Finance.

This namespace handles cookie/crumb authentication for Yahoo's restricted
endpoints (fundamentals, options, financial statements).

WARNING: This is experimental and may break at any time. Yahoo can:
- Change authentication at any time
- Block or rate-limit requests
- Detect automated access

For production use, consider stable alternatives:
- Alpha Vantage: https://www.alphavantage.co/
- Financial Modeling Prep: https://site.financialmodelingprep.com/
- Massive (formerly Polygon.io): https://massive.com/

Implementation notes:
- Uses singleton session (thread-unsafe, single-user)
- Cookies auto-refresh every hour
- MAX 1 retry on authentication failure
- Rate-limit protection via session reuse

EXPERIMENTAL: earnings report dates and EPS surprises.

- fetch-earnings-history / * - the last four quarters from the quoteSummary
  `earnings` module: fiscal period end paired with the date and time the
  results were reported, EPS actual vs. estimate.
- fetch-earnings-dates / *   - the longer history of earnings announcement
  events from Yahoo's visualization API (back to the 1990s for large US
  companies), with EPS estimate, actual and surprise.

Both use the authenticated session of clj-yfinance.experimental.auth.

Data notes (Yahoo's behaviour, not this library's):
- EPS here is the figure analysts estimate (usually adjusted, non-GAAP),
  which can differ from the reported diluted EPS of the statements.
- :period-end is normalised to the month end, as in the statements.
- The visualization history currently stops in mid-2025 (Yahoo no longer
  seems to update it); fetch-earnings-history covers the recent quarters.

WARNING: Yahoo does not document these endpoints and can change them at any
time.

EXPERIMENTAL: Fetch data from Yahoo Finance quoteSummary endpoint.

This namespace provides access to company data via Yahoo's authenticated
quoteSummary API. The underlying fetch-quotesummary* function accepts any
combination of quoteSummary modules, making it easy to add new data types.

Available modules (pass to fetch-quotesummary*):
- financialData            - Price targets, margins, revenue, cash flow
- defaultKeyStatistics     - P/E, market cap, beta, shares outstanding
- assetProfile             - Sector, industry, description, employees
- earningsTrend            - Analyst EPS/revenue estimates by period
- recommendationTrend      - Buy/hold/sell counts over time
- earningsHistory          - Historical EPS vs estimates
- incomeStatementHistory   - Annual/quarterly income statements
- balanceSheetHistory      - Annual/quarterly balance sheets
- cashflowStatementHistory - Annual/quarterly cash flow statements
- calendarEvents           - Upcoming earnings and dividend dates

WARNING: This is experimental and may break at any time. Yahoo can change
or block authentication without notice.

For production use, consider stable alternatives:
- Alpha Vantage (free tier, good fundamentals)
- Financial Modeling Prep (comprehensive)
- Massive, formerly Polygon.io (professional-grade)

Implementation notes:
- Returns ALL fields from Yahoo (no filtering)
- Session auto-refreshes every hour
- MAX 1 retry on authentication failure

EXPERIMENTAL: Fetch options chain data from Yahoo Finance.

This namespace provides access to options chains via Yahoo's authenticated
v7 options endpoint. Authentication is handled automatically via the shared
session in clj-yfinance.experimental.auth.

WARNING: This is experimental and may break at any time. Yahoo can change
or block authentication without notice.

For production use, consider stable alternatives:
- Alpha Vantage (free tier, options data available)
- Massive, formerly Polygon.io (professional-grade, comprehensive options)
- Tradier (options-focused API)

Implementation notes:
- Uses /v7/finance/options endpoint (different from quoteSummary)
- Without :expiration returns nearest expiry + full list of available dates
- With :expiration (epoch seconds) returns full calls/puts chain for that date
- Each contract map includes: strike, bid, ask, lastPrice, impliedVolatility,
  openInterest, volume, inTheMoney, contractSymbol, expiration, lastTradeDate
- Session auto-refreshes every hour
- MAX 1 retry on authentication failure

EXPERIMENTAL: financial statements from Yahoo's fundamentals-timeseries
endpoint.

This is the endpoint Yahoo's own financials pages use. Unlike the
quoteSummary statement modules (see fetch-financials in
clj-yfinance.experimental.fundamentals, which Yahoo has cut down to a few
fields), it returns the full income statement, balance sheet and cash flow
statement. It needs no cookie or crumb.

- fetch-statements / fetch-statements* - statement line items as tidy rows
- fetch-timeseries / fetch-timeseries* - raw access by Yahoo type string
  (e.g. "quarterlyTotalRevenue")
- statement-fields, field->keyword      - the field catalog

Data notes (Yahoo's behaviour, not this library's):
- Typical depth is 4 annual, 5 quarterly and a few trailing (TTM) points.
- Period ends are normalised to month ends: a fiscal quarter ending
  Saturday 2025-09-27 is reported as "2025-09-30".
- Annual and quarterly per-share values are restated to the current share
  basis (NVDA's FY2024 diluted EPS comes back as 1.19, not the 11.93
  reported before its 2024 10:1 split). Trailing points are not always
  restated.
- :currency is the reporting currency, which can differ from the trading
  currency (0005.HK reports in USD).
- There is no trailing balance sheet.

WARNING: Yahoo does not document this endpoint and can change it at any time.