Repository Public
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