//! zfin -- Zig Financial Data Library
//!
//! Fetches, caches, and analyzes US equity/ETF financial data from
//! multiple free-tier API providers (Tiingo, Twelve Data, Polygon, Finnhub,
//! Alpha Vantage). Includes Morningstar-style performance calculations.
//!
//! ## Getting Started
//!
//! Most consumers should start with `DataService`, which orchestrates
//! fetching, caching, and provider selection. Pair it with a `Config`
//! (populated from environment variables / .env) to get going:
//!
//! ```
//! const config = try zfin.Config.load(allocator);
//! var svc = zfin.DataService.init(allocator, config);
//! const result = try svc.getCandles("AAPL");
//! ```
//!
//! For portfolio workflows, load a Portfolio from an SRF file and pass
//! it through `risk` and `performance` for analytics.

// ── Data Models ──────────────────────────────────────────────

/// Calendar date with financial-market helpers (trading days, expiry rules).
pub const Date = @import("models/date.zig").Date;

/// OHLCV price bar (open, high, low, close, volume) for a single trading day.
pub const Candle = @import("models/candle.zig").Candle;

/// Cash dividend payment with ex-date, pay-date, and amount.
pub const Dividend = @import("models/dividend.zig").Dividend;

/// Stock split event (ratio + effective date).
pub const Split = @import("models/split.zig").Split;

/// Single options contract (strike, expiry, greeks, bid/ask).
pub const OptionContract = @import("models/option.zig").OptionContract;

/// Full options chain for a symbol (calls + puts grouped by expiry).
pub const OptionsChain = @import("models/option.zig").OptionsChain;

/// Quarterly earnings event with EPS estimate, actual, and surprise.
pub const EarningsEvent = @import("models/earnings.zig").EarningsEvent;

/// ETF profile: expense ratio, AUM, top holdings, sector weights.
pub const EtfProfile = @import("models/etf_profile.zig").EtfProfile;

/// A single position lot (shares, cost basis, purchase date, type).
pub const Lot = @import("models/portfolio.zig").Lot;

/// Aggregated position: symbol + all its lots.
pub const Position = @import("models/portfolio.zig").Position;

/// Parsed portfolio: positions, cash, CDs, options, metadata.
pub const Portfolio = @import("models/portfolio.zig").Portfolio;

/// Real-time or delayed price quote (last, bid, ask, volume).
pub const Quote = @import("models/quote.zig").Quote;

// ── Infrastructure ───────────────────────────────────────────

/// Runtime configuration loaded from environment / .env file (API keys, paths).
pub const Config = @import("config.zig").Config;

// ── Cache ────────────────────────────────────────────────────

/// SRF-backed file cache for candles, dividends, earnings, and other fetched data.
pub const cache = @import("cache/store.zig");

// ── Analytics ────────────────────────────────────────────────

/// Morningstar-style holding-period return calculations (total + annualized).
pub const performance = @import("analytics/performance.zig");

/// Portfolio risk metrics: volatility, Sharpe ratio, max drawdown.
pub const risk = @import("analytics/risk.zig");

/// Portfolio valuation: summary, allocations, historical snapshots, fallback prices.
pub const valuation = @import("analytics/valuation.zig");

/// Technical indicators: SMA, EMA, Bollinger Bands, RSI, MACD.
pub const indicators = @import("analytics/indicators.zig");

/// Fundamental analysis: valuation, momentum, quality, and yield scoring.
pub const analysis = @import("analytics/analysis.zig");

// ── Classification ───────────────────────────────────────────

/// Sector/industry/country classification for enriched securities.
pub const classification = @import("models/classification.zig");

// ── Service Layer ────────────────────────────────────────────

/// High-level data service: orchestrates providers, caching, and fallback logic.
pub const DataService = @import("service.zig").DataService;

/// Errors returned by DataService (NoApiKey, RateLimited, etc.).
pub const DataError = @import("service.zig").DataError;

/// Company overview data (sector, industry, country, market cap) from Alpha Vantage.
pub const CompanyOverview = @import("service.zig").CompanyOverview;

/// Result of a CUSIP-to-ticker lookup (ticker, name, security type).
pub const CusipResult = @import("service.zig").CusipResult;