SPB Git

Repository Public

VQMarketData.swift 22.6 KB 448 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sources/VQuantKit/Data/VQMarketData.swift3// Description: The data layer of CONTRACT §3: bars with provenance, quotes, statements, market overview, data health,4//              universal search.5import Foundation67// MARK: bars89public struct VQBar: Sendable, Equatable {10    /// Epoch seconds: 00:00 UTC of the session date for a daily bar, the bar's start for an intraday bar.11    public var t: Double12    public var open: Double?, high: Double?, low: Double?, close: Double?, volume: Double?13    public var date: Date { Date(timeIntervalSince1970: t) }14    public init(t: Double, open: Double?, high: Double?, low: Double?, close: Double?, volume: Double?) {15        self.t = t; self.open = open; self.high = high; self.low = low; self.close = close; self.volume = volume16    }17    init?(row: VQJSON) {18        guard let a = row.arrayValue, let t = a.first?.doubleValue else { return nil }19        func v(_ i: Int) -> Double? { a.indices.contains(i) ? a[i].doubleValue : nil }20        self.init(t: t, open: v(1), high: v(2), low: v(3), close: v(4), volume: v(5))21    }22}2324/// `GET /api/v2/data/bars/:symbol` — one provider per series, never mixed.25public struct VQBarSeries: Sendable, Equatable, VQJSONDecodable {26    public var symbol: String27    public var interval: String28    /// Ascending.29    public var bars: [VQBar]30    public var provenance: Provenance3132    public struct Provenance: Sendable, Equatable, VQJSONDecodable {33        public var provider: String34        /// The provider asked first, when this series comes from the fallback.35        public var fallbackFrom: String?36        public var fallbackReason: String?37        public var retrievedAt: Date?38        /// The adjustment the series really has (`split_div` | `split` | `none`).39        public var adjust: String?40        public var adjustRequested: String?41        public var assetClass: String?42        public var exchange: String?43        public var timezone: String?44        public var currency: String?45        public var freshness: VQFreshness?46        public var observations: Int?47        public var firstDate: String?48        public var lastDate: String?49        public var truncated: Bool50        public var gaps: Gaps?51        public var notes: [String]52        public init(json j: VQJSON) {53            provider = j.str("provider"); fallbackFrom = j.optStr("fallbackFrom"); fallbackReason = j.optStr("fallbackReason")54            retrievedAt = j.date("retrievedAt"); adjust = j.optStr("adjust"); adjustRequested = j.optStr("adjustRequested")55            assetClass = j.optStr("assetClass"); exchange = j.optStr("exchange"); timezone = j.optStr("timezone"); currency = j.optStr("currency")56            freshness = j.model("freshness"); observations = j.int("observations"); firstDate = j.optStr("firstDate"); lastDate = j.optStr("lastDate")57            truncated = j.flag("truncated"); gaps = j.model("gaps"); notes = j.strings("notes")58        }59    }60    /// Daily series only: sessions missing between the first and last bar.61    public struct Gaps: Sendable, Equatable, VQJSONDecodable {62        public var missingSessions: Int63        public var missingDates: [String]64        public var unexpectedSessions: Int65        public var unexpectedDates: [String]66        /// `exchange` | `weekdays` | `every_day` | `none`67        public var calendar: String?68        public var checkedFrom: String?69        public var checkedTo: String?70        public var note: String?71        public init(json j: VQJSON) {72            missingSessions = j.int("missingSessions") ?? 0; missingDates = j.strings("missingDates")73            unexpectedSessions = j.int("unexpectedSessions") ?? 0; unexpectedDates = j.strings("unexpectedDates")74            calendar = j.optStr("calendar"); checkedFrom = j.optStr("checkedFrom"); checkedTo = j.optStr("checkedTo"); note = j.optStr("note")75        }76    }77    public init(json j: VQJSON) {78        symbol = j.str("symbol"); interval = j.str("interval", "1d"); bars = j.list("bars").compactMap(VQBar.init(row:))79        provenance = Provenance(json: j["provenance"] ?? .null)80    }81}8283// MARK: quotes8485public struct VQQuote: Sendable, Equatable, Identifiable, VQJSONDecodable {86    public var symbol: String87    public var name: String?88    public var price: Double?89    public var change: Double?90    /// In **percentage points** (−1.24 = −1.24 %): format with `VQFormat.percentValue`.91    public var changePct: Double?92    public var currency: String?93    public var open: Double?, previousClose: Double?94    public var dayLow: Double?, dayHigh: Double?, yearLow: Double?, yearHigh: Double?95    /// nil where it does not apply (pairs, indices).96    public var volume: Double?97    public var marketCap: Double?98    public var exchange: String?99    public var assetClass: String?100    public var provider: String?101    public var providerTimestamp: Date?102    /// This quote's own freshness kind (`polled`, or `delayed` for EODHD).103    public var freshness: VQOpen<VQFreshness.Kind>?104    public var id: String { symbol }105    public init(json j: VQJSON) {106        symbol = j.str("symbol"); name = j.optStr("name"); price = j.num("price"); change = j.num("change"); changePct = j.num("changePct")107        currency = j.optStr("currency"); open = j.num("open"); previousClose = j.num("previousClose")108        dayLow = j.num("dayLow"); dayHigh = j.num("dayHigh"); yearLow = j.num("yearLow"); yearHigh = j.num("yearHigh")109        volume = j.num("volume"); marketCap = j.num("marketCap"); exchange = j.optStr("exchange"); assetClass = j.optStr("assetClass")110        provider = j.optStr("provider"); providerTimestamp = j.date("providerTimestamp"); freshness = j.optOpen("freshness")111    }112}113114public struct VQQuotes: Sendable, Equatable, VQJSONDecodable {115    public var quotes: [VQQuote]116    /// Symbols nobody quoted.117    public var missing: [String]118    public var freshness: VQFreshness?119    public init(json j: VQJSON) { quotes = j.models("quotes"); missing = j.strings("missing"); freshness = j.model("freshness") }120    public subscript(symbol: String) -> VQQuote? { quotes.first { $0.symbol == symbol } }121}122123// MARK: statements124125public struct VQStatements: Sendable, Equatable, VQJSONDecodable {126    public var symbol: String127    public var currency: String?128    /// `annual` | `quarter`129    public var period: String?130    /// Newest first; `Row.values[i]` belongs to `periods[i]`.131    public var periods: [Period]132    public var income: [Row], balance: [Row], cashflow: [Row]133    /// Also holds the per-share rows.134    public var ratios: [Row]135    public var growth: [Row]136    public var commonSizeIncome: [Row], commonSizeBalance: [Row]137    /// Common-size cash flow rows, when the server provides them (empty otherwise).138    public var commonSizeCashflow: [Row]139    public var provenance: Provenance?140141    public struct Period: Sendable, Equatable, VQJSONDecodable {142        public var date: String143        public var fiscalYear: String?144        public var period: String?145        public var filingDate: String?146        public init(json j: VQJSON) {147            date = j.str("date"); fiscalYear = j["fiscalYear"]?.displayString; period = j.optStr("period"); filingDate = j.optStr("filingDate")148        }149        /// "FY 2026", "Q3 2026"150        public var label: String { [period, fiscalYear].compactMap { $0 }.joined(separator: " ") }151    }152    public struct Row: Sendable, Equatable, Identifiable, VQJSONDecodable {153        public enum Unit: String, Sendable, Hashable, CaseIterable { case currency, ratio, percent, perShare = "per_share", count }154        public var key: String155        public var label: String156        /// `percent` and `ratio` values are **fractions** (0.25 = 25 %).157        public var unit: VQOpen<Unit>158        public var values: [Double?]159        /// The transparent calculation of a derived row.160        public var formula: String?161        public var id: String { key }162        public init(json j: VQJSON) {163            key = j.str("key"); label = j.str("label", key); unit = j.open("unit", .count); values = j.list("values").map(\.doubleValue); formula = j.optStr("formula")164        }165        public var valueUnit: VQValueUnit { VQValueUnit(rawValue: unit.rawValue) ?? .none }166    }167    public struct Provenance: Sendable, Equatable, VQJSONDecodable {168        public var provider: String169        public var retrievedAt: Date?170        public var freshness: VQFreshness?171        public var notes: [String]172        public init(json j: VQJSON) { provider = j.str("provider"); retrievedAt = j.date("retrievedAt"); freshness = j.model("freshness"); notes = j.strings("notes") }173    }174    public init(json j: VQJSON) {175        symbol = j.str("symbol"); currency = j.optStr("currency"); period = j.optStr("period"); periods = j.models("periods")176        income = j.models("income"); balance = j.models("balance"); cashflow = j.models("cashflow"); ratios = j.models("ratios"); growth = j.models("growth")177        let cs = j["commonSize"] ?? .null178        commonSizeIncome = cs.models("income"); commonSizeBalance = cs.models("balance"); commonSizeCashflow = cs.models("cashflow"); provenance = j.model("provenance")179    }180}181182// MARK: market overview183184public struct VQMarketOverview: Sendable, Equatable, VQJSONDecodable {185    public var asOf: Date?186    public var status: Status187    public var sections: [Section]188    public var yieldCurve: YieldCurve?189    public var calendar: [CalendarEvent]190    public var calendarFreshness: VQFreshness?191192    public struct Status: Sendable, Equatable, VQJSONDecodable {193        public enum Session: String, Sendable, Hashable, CaseIterable { case pre, regular, post, closed }194        public var isOpen: Bool195        public var session: VQOpen<Session>196        public var note: String?197        public init(json j: VQJSON) { isOpen = j.flag("isOpen"); session = j.open("session", .closed); note = j.optStr("note") }198    }199    public struct Section: Sendable, Equatable, Identifiable, VQJSONDecodable {200        /// `indices` | `sectors` | `rates` | `fx` | `commodities` | `crypto` | `volatility` | `movers` (or a section added later)201        public var id: String202        public var title: String203        /// false: the provider refused it; `items` is empty and `freshness.note` says why.204        public var available: Bool205        public var freshness: VQFreshness?206        public var items: [Item]207        public init(json j: VQJSON) { id = j.str("id"); title = j.str("title", id); available = j.flag("available", true); freshness = j.model("freshness"); items = j.models("items") }208    }209    public struct Item: Sendable, Equatable, Identifiable, VQJSONDecodable {210        public enum Unit: String, Sendable, Hashable, CaseIterable { case points, rate, currency, yieldPct = "yield_pct", pctChange = "pct_change" }211        /// nil for sector rows.212        public var symbol: String?213        public var name: String214        public var price: Double?215        /// Treasury yields: percentage points vs the previous day.216        public var change: Double?217        /// Percentage points.218        public var changePct: Double?219        public var unit: VQOpen<Unit>?220        /// `group` (`gainers|losers|actives`) for movers, `currency`, `exchange`, `months`, day range…221        public var extra: VQJSONObject222        public var id: String { symbol ?? name }223        public init(json j: VQJSON) {224            symbol = j.optStr("symbol"); name = j.str("name"); price = j.num("price"); change = j.num("change"); changePct = j.num("changePct")225            unit = j.optOpen("unit"); extra = j.dict("extra")226        }227        public var group: String? { extra["group"]?.stringValue }228        public var currency: String? { extra["currency"]?.stringValue }229    }230    public struct YieldCurve: Sendable, Equatable, VQJSONDecodable {231        public var date: String232        public var points: [Point]233        /// The latest day ≥ 28 days before `date` (nil if none).234        public var previous: Previous?235        public var freshness: VQFreshness?236        public struct Point: Sendable, Equatable, VQJSONDecodable {237            public var tenor: String238            public var months: Double239            /// Percent.240            public var yield: Double?241            public init(json j: VQJSON) { tenor = j.str("tenor"); months = j.num("months") ?? 0; self.yield = j.num("yield") }242        }243        public struct Previous: Sendable, Equatable, VQJSONDecodable {244            public var date: String245            public var points: [Point]246            public init(json j: VQJSON) { date = j.str("date"); points = j.models("points") }247        }248        public init(json j: VQJSON) { date = j.str("date"); points = j.models("points"); previous = j.model("previous"); freshness = j.model("freshness") }249    }250    public struct CalendarEvent: Sendable, Equatable, VQJSONDecodable {251        /// ISO UTC.252        public var date: String253        public var event: String254        public var country: String?255        public var currency: String?256        public var actual: Double?, estimate: Double?, previous: Double?257        public var impact: String?258        public var unit: String?259        public init(json j: VQJSON) {260            date = j.str("date"); event = j.str("event"); country = j.optStr("country"); currency = j.optStr("currency")261            actual = j.num("actual"); estimate = j.num("estimate"); previous = j.num("previous"); impact = j.optStr("impact"); unit = j.optStr("unit")262        }263        public var when: Date? { VQISODate.parse(date) }264    }265    public init(json j: VQJSON) {266        asOf = j.date("asOf"); status = Status(json: j["status"] ?? .null); sections = j.models("sections"); yieldCurve = j.model("yieldCurve")267        calendar = j.models("calendar"); calendarFreshness = j.model("calendarFreshness")268    }269    public func section(_ id: String) -> Section? { sections.first { $0.id == id } }270}271272// MARK: data health273274public struct VQDataHealth: Sendable, Equatable, VQJSONDecodable {275    public var providers: [Provider]276    public var checkedAt: Date?277    public struct Provider: Sendable, Equatable, Identifiable, VQJSONDecodable {278        public var id: String279        public var name: String280        public var configured: Bool281        public var ok: Bool282        public var latencyMs: Double?283        public var checkedAt: Date?284        public var error: String?285        /// Labels of the capabilities that answered with data.286        public var coverage: [String]287        public var notes: String?288        public var capabilities: [Capability]289        /// Counters of the data layer since the server started.290        public var calls: Int?, errors: Int?291        public var lastError: String?292        public var lastErrorAt: Date?293        public init(json j: VQJSON) {294            id = j.str("id"); name = j.str("name", id); configured = j.flag("configured"); ok = j.flag("ok"); latencyMs = j.num("latencyMs")295            checkedAt = j.date("checkedAt"); error = j.optStr("error"); coverage = j.strings("coverage")296            notes = j.optStr("notes") ?? (j.strings("notes").isEmpty ? nil : j.strings("notes").joined(separator: " "))297            capabilities = j.models("capabilities"); calls = j.int("calls"); errors = j.int("errors"); lastError = j.optStr("lastError"); lastErrorAt = j.date("lastErrorAt")298        }299    }300    public struct Capability: Sendable, Equatable, Identifiable, VQJSONDecodable {301        public enum Status: String, Sendable, Hashable, CaseIterable { case ok, plan, empty, notFound = "not_found", rateLimit = "rate_limit", timeout, network, error }302        public var id: String303        public var label: String304        public var ok: Bool305        public var status: VQOpen<Status>306        public var detail: String?307        public var latencyMs: Double?308        public var checkedAt: Date?309        public init(json j: VQJSON) {310            id = j.str("id"); label = j.str("label", id); ok = j.flag("ok"); status = j.open("status", .error); detail = j.optStr("detail")311            latencyMs = j.num("latencyMs"); checkedAt = j.date("checkedAt")312        }313    }314    public init(json j: VQJSON) { providers = j.models("providers"); checkedAt = j.date("checkedAt") }315}316317// MARK: universal search318319public struct VQSearchResults: Sendable, Equatable, VQJSONDecodable {320    public var results: [VQSearchResult]321    /// Result types whose source did not answer in time (e.g. `symbol` when the provider is slow).322    public var unavailable: [String]323    public init(json j: VQJSON) { results = j.models("results"); unavailable = j.strings("unavailable") }324}325326public struct VQSearchResult: Sendable, Equatable, Identifiable, VQJSONDecodable {327    public enum ResultType: String, Sendable, Hashable, CaseIterable {328        case symbol, conversation, project, note, watchlist, portfolio, chart, report, indicator, action329    }330    public var type: VQOpen<ResultType>331    /// Ticker, session id, object id; for actions `nav:<place>` or `engine:<engine id>`.332    public var resultId: String333    public var title: String334    public var subtitle: String?335    public var symbol: String?336    public var exchange: String?337    public var assetClass: String?338    /// 0–1; the list is sorted by it.339    public var score: Double340    public var id: String { "\(type.rawValue):\(resultId)" }341    public init(json j: VQJSON) {342        type = j.open("type", .action); resultId = j.str("id"); title = j.str("title"); subtitle = j.optStr("subtitle"); symbol = j.optStr("symbol")343        exchange = j.optStr("exchange"); assetClass = j.optStr("assetClass"); score = j.num("score") ?? 0344    }345346    /// What an `action` result asks the app to do; each client maps it to its own route.347    public enum Action: Sendable, Equatable {348        /// `home`, `chat`, `terminal`, `markets`, `charts`, `quant`, `portfolio`, `watchlists`, `research`, `notes`,349        /// `history`, `statements`, `options`, `macro`, `agent`, `usage`, `settings`, `security` — or a place added later.350        case navigate(String)351        case openEngine(String)352        case other(String)353    }354    public var action: Action? {355        guard type == .action else { return nil }356        if resultId.hasPrefix("nav:") { return .navigate(String(resultId.dropFirst(4))) }357        if resultId.hasPrefix("engine:") { return .openEngine(String(resultId.dropFirst(7))) }358        return .other(resultId)359    }360}361362// MARK: client363364public struct VQDataClient: Sendable {365    public let client: VQClient366    public init(client: VQClient) { self.client = client }367368    /// - Parameters:369    ///   - interval: `1m|5m|15m|30m|1h|4h|1d`370    ///   - from/to: ISO dates; without `from` the server picks a window per interval.371    ///   - adjust: `split_div` | `split` | `none` (what is asked; `provenance.adjust` says what the series really has)372    ///   - limit: 1–50 000; keeps the most recent bars.373    public func bars(_ symbol: String, interval: String = "1d", from: String? = nil, to: String? = nil, adjust: String? = nil, limit: Int? = nil) async throws -> VQBarSeries {374        let q = [VQQueryItem("interval", interval)] + VQQueryItem.optional("from", from) + VQQueryItem.optional("to", to)375            + VQQueryItem.optional("adjust", adjust) + VQQueryItem.optional("limit", limit.map(String.init))376        return try await client.decode(.get("/api/v2/data/bars/\(VQRequest.segment(symbol))", q, timeout: 60))377    }378379    /// At most 60 symbols.380    public func quotes(_ symbols: [String]) async throws -> VQQuotes {381        try await client.decode(.get("/api/v2/data/quotes", [VQQueryItem("symbols", symbols.joined(separator: ","))]))382    }383384    public func statements(_ symbol: String, period: String = "annual", limit: Int = 8) async throws -> VQStatements {385        try await client.decode(.get("/api/v2/data/statements/\(VQRequest.segment(symbol))", [VQQueryItem("period", period), VQQueryItem("limit", String(limit))], timeout: 60))386    }387388    public func marketOverview() async throws -> VQMarketOverview { try await client.decode(.get("/api/v2/market/overview", timeout: 60)) }389390    public func health() async throws -> VQDataHealth { try await client.decode(.get("/api/v2/data/health", timeout: 60)) }391392    /// An empty `query` returns the navigation targets.393    public func search(_ query: String, types: [VQSearchResult.ResultType]? = nil, limit: Int? = nil) async throws -> VQSearchResults {394        let q = [VQQueryItem("q", query)] + VQQueryItem.optional("types", types.map { $0.map(\.rawValue).joined(separator: ",") })395            + VQQueryItem.optional("limit", limit.map(String.init))396        return try await client.decode(.get("/api/v2/search", q))397    }398399    /// The per-provider reasons of a bars failure (404 / 502): `[{ provider, reason }]`.400    public static func providerReasons(of error: VQError) -> [(provider: String, reason: String)] {401        (error.body?["providers"]?.arrayValue ?? []).map { ($0.str("provider"), $0.str("reason")) }402    }403}404405/// ISO dates of the API: `YYYY-MM-DD` (read as 00:00 UTC) and ISO datetimes with or without fractional seconds / zone.406public enum VQISODate {407    public static func parse(_ text: String) -> Date? {408        let s = text.trimmingCharacters(in: .whitespaces)409        let u = Array(s.utf8)410        func n(_ from: Int, _ len: Int) -> Int? {411            guard u.count >= from + len else { return nil }412            var v = 0413            for i in from..<(from + len) { guard u[i] >= 48, u[i] <= 57 else { return nil }; v = v * 10 + Int(u[i] - 48) }414            return v415        }416        guard u.count >= 10, u[4] == 45, u[7] == 45, let y = n(0, 4), let m = n(5, 2), let d = n(8, 2), (1...12).contains(m), (1...31).contains(d) else { return nil }417        var hh = 0, mm = 0, ss = 0.0, offset = 0418        if u.count > 10 {419            guard u[10] == 84 || u[10] == 32, let h = n(11, 2), u.count >= 16, u[13] == 58, let mi = n(14, 2) else { return nil }420            hh = h; mm = mi421            var i = 16422            if u.count > i, u[i] == 58, let sec = n(i + 1, 2) {423                ss = Double(sec); i += 3424                if u.count > i, u[i] == 46 {425                    var j = i + 1, scale = 0.1426                    while j < u.count, u[j] >= 48, u[j] <= 57 { ss += Double(u[j] - 48) * scale; scale /= 10; j += 1 }427                    i = j428                }429            }430            if u.count > i {431                if u[i] == 90 { offset = 0 }432                else if u[i] == 43 || u[i] == 45, let oh = n(i + 1, 2) {433                    let om = n(i + 4, 2) ?? n(i + 3, 2) ?? 0434                    offset = (oh * 3600 + om * 60) * (u[i] == 45 ? -1 : 1)435                }436            }437        }438        // days from civil (proleptic Gregorian), no Calendar needed439        let yy = m <= 2 ? y - 1 : y440        let era = (yy >= 0 ? yy : yy - 399) / 400441        let yoe = yy - era * 400442        let doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + d - 1443        let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy444        let days = era * 146097 + doe - 719468445        return Date(timeIntervalSince1970: Double(days) * 86400 + Double(hh * 3600 + mm * 60) + ss - Double(offset))446    }447}448
Files main
Menu

Theme