# Changelog

All notable changes to Stock Oracle API will be documented in this file.

## [3.0.1] - 2026-03-14

### Added
- **Filing Search `accepted_at` field**: `GET /filings/search/{ticker}` response now includes `accepted_at` (ISO 8601 timestamp) in each `FilingSummary`
  - Sourced from `acceptanceDateTime` in SEC EDGAR submissions JSON — no additional HTTP requests needed
  - `SECFiling` DB model gains a nullable `accepted_at TIMESTAMP` column
  - SQLite auto-migration: `ALTER TABLE sec_filings ADD COLUMN accepted_at TIMESTAMP` runs at startup (idempotent)
  - Existing rows have `accepted_at = NULL`; re-index with `force_refresh=true` to backfill
  - Enables downstream consumers (e.g. `filing_poller`) to populate `Document.accepted_at_utc` and `Event.filed_at_utc`

## [3.0.0] - 2026-03-12

### Added
- **Alpaca Market Data Adapter**: Complete integration with Alpaca Market Data API v2
  - `GET /alpaca/status` — Connection status and API key validation
  - `GET /alpaca/bars/{ticker}` — Raw bars from Alpaca (no DB)
  - `GET /alpaca/data/{ticker}` — OHLCV price data with DB storage (PriceDataResponse format)
  - `GET /alpaca/intraday/{ticker}` — Intraday candles (1m, 5m, 15m, 1h)
  - Built-in rate limiting (200 req/min token bucket) with retry + exponential backoff
  - VWAP (volume-weighted average price) and trade count per bar
  - Auto-pagination for large date ranges
  - Completely independent from Yahoo Finance — users choose their source

- **FINRA Short Sale Volume Adapter**: RegSHO daily short volume data
  - `GET /finra/short-volume/{symbol}` — Short volume data with auto-ingest
  - `GET /finra/short-ratio/{symbol}` — Aggregated short ratio history
  - `POST /finra/admin/ingest` — Manual ingest for single date or date range
  - Public FINRA CDN data (no API key required)
  - Pipe-delimited text parser for CNMS short volume files
  - Multi-market data (NYSE TRF, NASDAQ TRF, NYSE)
  - Auto-ingest on first query if data is missing

- **New DB Model**: `FinraShortVolume` with `(symbol, date, market)` unique constraint
- **New DataSource Enum**: `DataSource.ALPACA` added to schema
- **Configuration**: `ALPACA_API_KEY`, `ALPACA_SECRET_KEY`, `ALPACA_BASE_URL` settings
- **Docker**: Alpaca env vars passed to API container

### New Files
- `app/services/alpaca_client.py` — Alpaca HTTP client with httpx
- `app/services/alpaca_price_service.py` — Alpaca bars → PriceData conversion
- `app/api/v1/endpoints/alpaca.py` — Alpaca endpoints
- `app/models/finra_short_volume.py` — FINRA SQLAlchemy model
- `app/services/finra_short_volume_service.py` — FINRA fetch/parse/ingest service
- `app/schemas/finra.py` — FINRA Pydantic schemas
- `app/api/v1/endpoints/finra.py` — FINRA endpoints

## [2.1.0] - 2025-08-10

### Added
- **ETF Holdings API v2**: Complete rewrite with enhanced features
  - `availability` field in all error responses showing available date ranges
  - ETF launch date validation to prevent invalid historical requests
  - Automatic detection when ETF didn't exist on requested date
  - Fast performance optimization (<0.1s response time, down from 35s)
  - Enhanced error messages with actionable information

### Improved
- **Performance**: ETF date validation now uses cached launch dates for instant response
- **User Experience**: Clear error messages when ETF data is unavailable
- **Documentation**: Comprehensive API documentation with examples

### Fixed
- Historical date requests now correctly validate against ETF launch dates
- QQQM pre-launch date requests now return proper error instead of wrong data
- Response model now includes all fields (fixed Pydantic model filtering issue)

## [2.0.0] - 2025-07-01

### Added
- **ETF Holdings API**: New endpoint for ETF portfolio data
  - Support for 30+ major ETFs with pre-configured mappings
  - Automatic CIK to ticker conversion
  - Historical NPORT data from 2019 onwards
  - Support for both ticker symbols and CIK numbers

### Changed
- Simplified ETF API to single `/holdings/{ticker}` endpoint
- Removed redundant ETF endpoints

## [1.5.0] - 2024-12-01

### Added
- **Price Data API**: OHLCV data integration with yfinance
- **Bulk Data Support**: Batch requests for multiple tickers
- **Period Strings**: Convenient time period specification (1y, 6m, 3m, etc.)

### Improved
- Database caching strategy
- Error handling and logging
- API documentation

## [1.0.0] - 2024-10-01

### Initial Release
- **Financial Data API**: SEC filing data extraction
- **Metrics Calculation**: P/E, P/B, ROE, margins, etc.
- **Database Caching**: SQLite/PostgreSQL support
- **Docker Deployment**: Complete containerization
- **API Documentation**: Interactive Swagger/OpenAPI docs