Emil Lerch
7fb674f467
This (huge) commit pulls out AlphaVantage in favor of utilizing Wikidata and SEC EDGAR data sources (both free). It uses some built-in heuristics to fill in gaps, and it is not 100% (never will be), but should get close enough to allow hand-editing of metadata.srf afterwords without too much labor
105 lines
4.8 KiB
Zig
105 lines
4.8 KiB
Zig
//! zfin -- Zig Financial Data Library
|
|
//!
|
|
//! Fetches, caches, and analyzes US equity/ETF financial data from
|
|
//! multiple free-tier API providers (Tiingo, Twelve Data, Polygon, FMP,
|
|
//! 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("Date.zig");
|
|
|
|
/// 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");
|
|
|
|
// ── 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;
|
|
|
|
/// Per-call options controlling cache vs network behavior.
|
|
/// Drives the `--refresh-data` global flag.
|
|
pub const FetchOptions = @import("service.zig").FetchOptions;
|
|
|
|
/// Result of a CUSIP-to-ticker lookup (ticker, name, security type).
|
|
pub const CusipResult = @import("service.zig").CusipResult;
|