gloomberb 0.7.5 → 0.8.1

package/src/sources/provider-router/document-routes.ts

@@ -0,0 +1,153 @@
+import type {
+  MarketDataRequestContext,
+  SecFilingItem,
+} from "../../types/data-provider";
+import { canonicalExchange } from "../../utils/exchanges";
+import {
+  buildVariantKey,
+  compactUrl,
+  selectCachedResource,
+} from "./cache";
+import { shouldLogProviderError } from "../provider-errors";
+import type { ProviderRouterCoreDeps, SourceResult } from "./route-types";
+import {
+  firstProviderResult,
+  makeRouterRevalidationKey,
+  resolveProviderBySourceKey,
+  scheduleRouterRevalidation,
+} from "./routing";
+
+export class ProviderRouterDocumentRoutes {
+  private readonly revalidationInFlight = new Map<string, Promise<unknown>>();
+
+  constructor(private readonly deps: ProviderRouterCoreDeps) {}
+
+  async getSecFilings(ticker: string, count = 15, exchange?: string, context?: MarketDataRequestContext): Promise<SecFilingItem[]> {
+    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
+    const variantKeys = [
+      buildVariantKey([["exchange", canonicalExchange(exchange)], ["count", count]]),
+      buildVariantKey([["count", count]]),
+      "",
+    ];
+    const cached = selectCachedResource<SecFilingItem[]>(this.deps.resources, "sec-filings", entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
+    if (cached) {
+      scheduleRouterRevalidation(this.revalidationInFlight, makeRouterRevalidationKey(this.deps, "sec-filings", ticker, context, count), async () => {
+        await this.revalidateSecFilings(ticker, count, exchange, context);
+      });
+      return cached.value;
+    }
+
+    const result = await this.fetchProviderSecFilings(ticker, count, exchange, context);
+    if (!result) {
+      throw new Error(`No SEC filings provider available for ${ticker}`);
+    }
+    return result.value;
+  }
+
+  async getSecFilingContent(filing: SecFilingItem): Promise<string | null> {
+    const entityKey = compactUrl(filing.primaryDocumentUrl ?? filing.filingUrl);
+    const cached = selectCachedResource<string | null>(this.deps.resources, "sec-filing-content", entityKey, [""], this.deps.getProviderSourceKeys(), false);
+    if (cached) {
+      scheduleRouterRevalidation(this.revalidationInFlight, `sec-filing-content:${entityKey}`, async () => {
+        await this.revalidateSecFilingContent(filing);
+      });
+      return cached.value;
+    }
+
+    const result = await this.fetchProviderSecFilingContent(filing);
+    if (!result) {
+      throw new Error("No SEC filing content provider available");
+    }
+    return result.value;
+  }
+
+  async getArticleSummary(url: string): Promise<string | null> {
+    const entityKey = compactUrl(url);
+    const cached = selectCachedResource<string>(this.deps.resources, "article-summary", entityKey, [""], this.deps.getProviderSourceKeys(), false);
+    if (cached) {
+      scheduleRouterRevalidation(this.revalidationInFlight, `article-summary:${entityKey}`, async () => {
+        await this.revalidateArticleSummary(url);
+      });
+      return cached.value;
+    }
+
+    const result = await firstProviderResult(this.deps, (provider) => provider.getArticleSummary(url));
+    if (!result) {
+      return null;
+    }
+    const provider = resolveProviderBySourceKey(this.deps, result.sourceKey);
+    if (provider && result.value) {
+      this.deps.cacheResource("article-summary", entityKey, "", result.sourceKey, result.value, this.deps.resolveProviderPolicy("articleSummary", provider));
+    }
+    return result.value;
+  }
+
+  private async fetchProviderSecFilings(
+    ticker: string,
+    count = 15,
+    exchange?: string,
+    context?: MarketDataRequestContext,
+  ): Promise<SourceResult<SecFilingItem[]> | null> {
+    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
+    const variantKey = buildVariantKey([["exchange", canonicalExchange(exchange)], ["count", count]]);
+    let lastError: unknown = null;
+
+    for (const provider of this.deps.providersInPriorityOrder()) {
+      if (!provider.getSecFilings) continue;
+      try {
+        const value = await provider.getSecFilings(ticker, count, exchange, context);
+        const sourceKey = this.deps.providerSourceKey(provider);
+        this.deps.cacheResource("sec-filings", entityKey, variantKey, sourceKey, value, this.deps.resolveProviderPolicy("secFilings", provider));
+        return { sourceKey, value };
+      } catch (error) {
+        lastError = error;
+        if (shouldLogProviderError(error)) {
+          this.deps.logProviderError(`${provider.id} failed: ${error}`);
+        }
+      }
+    }
+
+    if (lastError) throw lastError;
+    return null;
+  }
+
+  private async fetchProviderSecFilingContent(filing: SecFilingItem): Promise<SourceResult<string | null> | null> {
+    const entityKey = compactUrl(filing.primaryDocumentUrl ?? filing.filingUrl);
+    let lastError: unknown = null;
+
+    for (const provider of this.deps.providersInPriorityOrder()) {
+      if (!provider.getSecFilingContent) continue;
+      try {
+        const value = await provider.getSecFilingContent(filing);
+        const sourceKey = this.deps.providerSourceKey(provider);
+        this.deps.cacheResource("sec-filing-content", entityKey, "", sourceKey, value, this.deps.resolveProviderPolicy("secFilingContent", provider));
+        return { sourceKey, value };
+      } catch (error) {
+        lastError = error;
+        if (shouldLogProviderError(error)) {
+          this.deps.logProviderError(`${provider.id} failed: ${error}`);
+        }
+      }
+    }
+
+    if (lastError) throw lastError;
+    return null;
+  }
+
+  private async revalidateSecFilings(ticker: string, count = 15, exchange?: string, context?: MarketDataRequestContext): Promise<void> {
+    await this.fetchProviderSecFilings(ticker, count, exchange, context);
+  }
+
+  private async revalidateSecFilingContent(filing: SecFilingItem): Promise<void> {
+    await this.fetchProviderSecFilingContent(filing);
+  }
+
+  private async revalidateArticleSummary(url: string): Promise<void> {
+    const result = await firstProviderResult(this.deps, (provider) => provider.getArticleSummary(url));
+    if (!result || !result.value) return;
+    const provider = resolveProviderBySourceKey(this.deps, result.sourceKey);
+    if (provider) {
+      this.deps.cacheResource("article-summary", compactUrl(url), "", result.sourceKey, result.value, this.deps.resolveProviderPolicy("articleSummary", provider));
+    }
+  }
+}

package/src/sources/provider-router/financial-routes.ts

@@ -0,0 +1,225 @@
+import type {
+  CachedFinancialsTarget,
+  MarketDataRequestContext,
+} from "../../types/data-provider";
+import type {
+  Quote,
+  TickerFinancials,
+} from "../../types/financials";
+import { parseOptionSymbol } from "../../utils/options";
+import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
+import { resolveTickerFinancialsQuoteState } from "../../market-data/quotes/resolution";
+import {
+  listCachedResources,
+  normalizeTicker,
+  selectCachedResource,
+  sortCachedRecords,
+} from "./cache";
+import { withBrokerTimeout } from "./brokers";
+import {
+  deriveMarketCapFromShares,
+  hasMeaningfulProfile,
+  mergeCachedFinancialRecords,
+  mergeFinancials,
+  quoteWithFreshnessExchange,
+  sanitizeCachedFinancials,
+  selectCachedQuoteRecord,
+  type CachedFinancialsReadOptions,
+  type CachedFinancialsSelection,
+} from "./financials";
+import type { ProviderRouterPrimaryRoutes } from "./primary";
+import type { ProviderRouterCoreDeps } from "./route-types";
+
+export interface ProviderRouterFinancialRouteDeps extends Pick<
+  ProviderRouterCoreDeps,
+  | "resources"
+  | "getEntityKey"
+  | "getTickerVariantCandidates"
+  | "getBrokerCandidatesForContext"
+  | "getProviderSourceKeys"
+  | "brokerSourceKey"
+> {
+  primaryRoutes: ProviderRouterPrimaryRoutes;
+}
+
+export class ProviderRouterFinancialRoutes {
+  constructor(private readonly deps: ProviderRouterFinancialRouteDeps) {}
+
+  getCachedFinancialsForTargets(
+    targets: CachedFinancialsTarget[],
+    options: { allowExpired?: boolean; includeStaleQuotes?: boolean } = {},
+  ): Map<string, TickerFinancials> {
+    const results = new Map<string, TickerFinancials>();
+    for (const target of targets) {
+      const cached = this.readCachedMergedFinancials(target.symbol, target.exchange, {
+        brokerId: target.brokerId,
+        brokerInstanceId: target.brokerInstanceId,
+        instrument: target.instrument ?? undefined,
+      }, options.allowExpired ?? true, {
+        includeStaleQuotes: options.includeStaleQuotes,
+        includeSymbolProviderFallback: true,
+      });
+      if (cached) results.set(target.symbol.toUpperCase(), cached);
+    }
+    return results;
+  }
+
+  async getTickerFinancials(
+    ticker: string,
+    exchange?: string,
+    context?: MarketDataRequestContext,
+  ): Promise<TickerFinancials> {
+    const isOptionTicker =
+      parseOptionSymbol(ticker) != null ||
+      parseOptionSymbol(context?.instrument?.localSymbol ?? "") != null ||
+      context?.instrument?.secType === "OPT";
+    const quoteOnlyFinancials = async (base?: TickerFinancials | null): Promise<TickerFinancials> => ({
+      ...base,
+      quote: await this.getQuote(ticker, exchange, context),
+      annualStatements: base?.annualStatements ?? [],
+      quarterlyStatements: base?.quarterlyStatements ?? [],
+      priceHistory: base?.priceHistory ?? [],
+    });
+    const cached = this.readCachedMergedFinancialsSelection(ticker, exchange, context, false);
+    const forceRefresh = context?.cacheMode === "refresh";
+    if (cached.value && !forceRefresh) {
+      if (isOptionTicker && !cached.value.quote) {
+        return quoteOnlyFinancials(cached.value);
+      }
+      if (!cached.stale && hasMeaningfulProfile(cached.value)) {
+        return cached.value;
+      }
+      if (!hasMeaningfulProfile(cached.value) && !cached.stale) {
+        const providerResult = await this.deps.primaryRoutes.fetchProviderFinancials(ticker, exchange, context);
+        return mergeFinancials(cached.value, providerResult?.value ?? null) ?? cached.value;
+      }
+    }
+
+    if (cached.value) {
+      const brokerResult = await withBrokerTimeout(this.deps.primaryRoutes.fetchBrokerFinancials(ticker, exchange, context));
+      const providerResult = await this.deps.primaryRoutes.fetchProviderFinancials(ticker, exchange, context);
+      const merged = mergeFinancials(
+        brokerResult?.value ?? cached.brokerRecord?.value ?? null,
+        providerResult?.value ?? cached.providerValue ?? null,
+      );
+      if (isOptionTicker && !merged?.quote) {
+        return quoteOnlyFinancials(merged ?? cached.value);
+      }
+      return merged ?? cached.value;
+    }
+
+    const brokerResult = await withBrokerTimeout(this.deps.primaryRoutes.fetchBrokerFinancials(ticker, exchange, context));
+    const fallback = await this.deps.primaryRoutes.fetchProviderFinancials(ticker, exchange, context);
+    const merged = mergeFinancials(brokerResult?.value ?? null, fallback?.value ?? null);
+    if (isOptionTicker && !merged?.quote) {
+      return quoteOnlyFinancials(merged);
+    }
+    if (!merged) {
+      throw new Error(`No provider available for ${ticker}`);
+    }
+    return merged;
+  }
+
+  async getQuote(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<Quote> {
+    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
+    const variantKeys = this.deps.getTickerVariantCandidates(exchange);
+    const sourceKeys = [
+      ...this.deps.getBrokerCandidatesForContext(context, false).map((candidate) => this.deps.brokerSourceKey(candidate)),
+      ...this.deps.getProviderSourceKeys(),
+    ];
+    const rawCached = selectCachedResource<Quote>(this.deps.resources, "quote", entityKey, variantKeys, sourceKeys, false);
+    const cached = rawCached && !isQuoteStaleForCurrentSession(quoteWithFreshnessExchange(rawCached.value, exchange))
+      ? rawCached
+      : null;
+    const forceRefresh = context?.cacheMode === "refresh";
+    if (cached && !forceRefresh && !cached.stale) {
+      return cached.value;
+    }
+
+    const brokerQuote = await withBrokerTimeout(this.deps.primaryRoutes.fetchBrokerQuote(ticker, exchange, context));
+    if (brokerQuote && !isQuoteStaleForCurrentSession(quoteWithFreshnessExchange(brokerQuote.value, exchange))) {
+      return brokerQuote.value;
+    }
+
+    const providerQuote = await this.deps.primaryRoutes.fetchProviderQuote(ticker, exchange, context);
+    if (providerQuote) {
+      return providerQuote.value;
+    }
+    if (cached) return cached.value;
+    throw new Error(`No quote provider available for ${ticker}`);
+  }
+
+  readCachedMergedFinancialsSelection(
+    ticker: string,
+    exchange?: string,
+    context?: MarketDataRequestContext,
+    allowExpired = false,
+    options: CachedFinancialsReadOptions = {},
+  ): CachedFinancialsSelection {
+    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
+    const variantKeys = this.deps.getTickerVariantCandidates(exchange);
+    const brokerSourceKeys = this.deps.getBrokerCandidatesForContext(context, false).map((candidate) => this.deps.brokerSourceKey(candidate));
+    const brokerRecord = brokerSourceKeys.length > 0
+      ? selectCachedResource<TickerFinancials>(this.deps.resources, "financials", entityKey, variantKeys, brokerSourceKeys, allowExpired)
+      : null;
+    const sanitizedBrokerRecord = brokerRecord
+      ? { ...brokerRecord, value: sanitizeCachedFinancials(brokerRecord.value, options) }
+      : null;
+    const providerSourceKeys = this.deps.getProviderSourceKeys();
+    const providerEntityKeys = options.includeSymbolProviderFallback
+      ? [...new Set([entityKey, normalizeTicker(ticker)])]
+      : [entityKey];
+    const providerRecords = sortCachedRecords(
+      providerEntityKeys.flatMap((providerEntityKey) => listCachedResources<TickerFinancials>(
+        this.deps.resources,
+        "financials",
+        providerEntityKey,
+        variantKeys,
+        providerSourceKeys,
+        allowExpired,
+      )),
+      variantKeys,
+      providerSourceKeys,
+    );
+    const providerSelection = mergeCachedFinancialRecords(
+      providerRecords,
+      options,
+    );
+    const quoteSourceKeys = [...brokerSourceKeys, ...providerSourceKeys];
+    const quoteRecords = sortCachedRecords(
+      providerEntityKeys.flatMap((quoteEntityKey) => listCachedResources<Quote>(
+        this.deps.resources,
+        "quote",
+        quoteEntityKey,
+        variantKeys,
+        quoteSourceKeys,
+        allowExpired,
+      )),
+      variantKeys,
+      quoteSourceKeys,
+    );
+    const quoteSelection = selectCachedQuoteRecord(quoteRecords, exchange, options);
+    const mergedValue = mergeFinancials(sanitizedBrokerRecord?.value ?? null, providerSelection.value);
+    const value = quoteSelection.quote
+      ? resolveTickerFinancialsQuoteState(mergedValue, quoteSelection.quote)
+      : mergedValue;
+    return {
+      brokerRecord: sanitizedBrokerRecord,
+      providerValue: providerSelection.value,
+      value: value
+        ? deriveMarketCapFromShares(value, { replaceExisting: !!quoteSelection.quote && quoteSelection.quote.marketCap == null })
+        : null,
+      stale: (sanitizedBrokerRecord?.stale ?? false) || providerSelection.stale || quoteSelection.stale,
+    };
+  }
+
+  private readCachedMergedFinancials(
+    ticker: string,
+    exchange?: string,
+    context?: MarketDataRequestContext,
+    allowExpired = false,
+    options: CachedFinancialsReadOptions = {},
+  ): TickerFinancials | null {
+    return this.readCachedMergedFinancialsSelection(ticker, exchange, context, allowExpired, options).value;
+  }
+}

package/src/sources/provider-router/financials.ts

@@ -0,0 +1,259 @@
+import type { CachedResourceRecord } from "../../data/resource-store";
+import type { AnalystResearchData, CorporateActionsData, FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
+import { hasLikelyQuoteUnitMismatch } from "../../utils/currency-units";
+import { normalizePriceHistory, normalizeTickerFinancialsPriceHistory } from "../../utils/price-history";
+import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
+import {
+  mergeQuoteContributionMaps,
+  resolveCanonicalQuote,
+  resolveTickerFinancialsQuoteState,
+  seedQuoteContributions,
+} from "../../market-data/quotes/resolution";
+
+export interface CachedFinancialsSelection {
+  brokerRecord: CachedResourceRecord<TickerFinancials> | null;
+  providerValue: TickerFinancials | null;
+  value: TickerFinancials | null;
+  stale: boolean;
+}
+
+export interface CachedFinancialsReadOptions {
+  includeStaleQuotes?: boolean;
+  includeSymbolProviderFallback?: boolean;
+}
+
+export interface CachedQuoteSelection {
+  quote: Quote | null;
+  stale: boolean;
+}
+
+export function deriveMarketCapFromShares(
+  financials: TickerFinancials,
+  options: { replaceExisting?: boolean } = {},
+): TickerFinancials {
+  const quote = financials.quote;
+  const sharesOutstanding = financials.fundamentals?.sharesOutstanding;
+  if (
+    !quote
+    || (quote.marketCap != null && !options.replaceExisting)
+    || !Number.isFinite(quote.price)
+    || !Number.isFinite(sharesOutstanding)
+    || quote.price <= 0
+    || !sharesOutstanding
+    || sharesOutstanding <= 0
+  ) {
+    return financials;
+  }
+
+  return {
+    ...financials,
+    quote: {
+      ...quote,
+      marketCap: quote.price * sharesOutstanding,
+    },
+  };
+}
+
+export function sanitizeCachedFinancials(
+  financials: TickerFinancials,
+  options: { includeStaleQuotes?: boolean } = {},
+): TickerFinancials {
+  const enriched = deriveMarketCapFromShares(financials);
+  if (options.includeStaleQuotes || !isQuoteStaleForCurrentSession(enriched.quote)) return enriched;
+  return {
+    ...enriched,
+    quote: undefined,
+    quoteContributions: undefined,
+  };
+}
+
+export function quoteWithFreshnessExchange(quote: Quote, exchange?: string): Quote {
+  if (!exchange || quote.listingExchangeName || quote.exchangeName) return quote;
+  return {
+    ...quote,
+    listingExchangeName: exchange,
+    exchangeName: exchange,
+  };
+}
+
+function sanitizeCachedQuote(
+  quote: Quote,
+  exchange: string | undefined,
+  options: { includeStaleQuotes?: boolean } = {},
+): Quote | null {
+  const normalized = quoteWithFreshnessExchange(quote, exchange);
+  return options.includeStaleQuotes || !isQuoteStaleForCurrentSession(normalized)
+    ? normalized
+    : null;
+}
+
+export function hasMeaningfulProfile(data: TickerFinancials | null | undefined): boolean {
+  return !!data && !!(
+    data.profile?.description
+    || data.profile?.sector
+    || data.profile?.industry
+  );
+}
+
+export function hasStatementRows(data: TickerFinancials | null | undefined): boolean {
+  return !!data && (
+    data.annualStatements.length > 0 ||
+    data.quarterlyStatements.length > 0
+  );
+}
+
+const DETAILED_STATEMENT_KEYS: Array<keyof FinancialStatement> = [
+  "accountsReceivable",
+  "inventory",
+  "stockBasedCompensation",
+  "purchaseOfPPE",
+  "cashFlowFromContinuingOperatingActivities",
+  "interestPaidSupplementalData",
+  "accountsPayable",
+  "currentDeferredRevenue",
+  "additionalPaidInCapital",
+  "totalNonCurrentAssets",
+  "totalNonCurrentLiabilities",
+];
+
+export function hasDetailedStatementRows(data: TickerFinancials | null | undefined): boolean {
+  if (!data) return false;
+  const rows = [...data.annualStatements, ...data.quarterlyStatements];
+  return rows.some((row) => DETAILED_STATEMENT_KEYS.some((key) => typeof row[key] === "number"));
+}
+
+function mergeStatementRows(
+  primaryRows: FinancialStatement[],
+  fallbackRows: FinancialStatement[],
+): FinancialStatement[] {
+  if (primaryRows.length === 0) return fallbackRows;
+  if (fallbackRows.length === 0) return primaryRows;
+
+  const fallbackByDate = new Map(fallbackRows.map((row) => [row.date, row]));
+  const primaryDates = new Set(primaryRows.map((row) => row.date));
+  const mergedRows = primaryRows.map((row) => ({
+    ...fallbackByDate.get(row.date),
+    ...row,
+    date: row.date,
+  }));
+
+  for (const row of fallbackRows) {
+    if (!primaryDates.has(row.date)) mergedRows.push(row);
+  }
+
+  return mergedRows.sort((left, right) => left.date.localeCompare(right.date));
+}
+
+export function mergeMissingStatementArrays(primary: TickerFinancials, fallback: TickerFinancials): TickerFinancials {
+  return {
+    ...primary,
+    annualStatements: mergeStatementRows(primary.annualStatements, fallback.annualStatements),
+    quarterlyStatements: mergeStatementRows(primary.quarterlyStatements, fallback.quarterlyStatements),
+  };
+}
+
+export function hasAnalystResearchValue(data: AnalystResearchData): boolean {
+  return !!data.priceTarget
+    || data.recommendations.length > 0
+    || data.ratings.length > 0
+    || data.earningsEstimates.length > 0
+    || data.revenueEstimates.length > 0;
+}
+
+function hasAnalystRatingPriceTargets(data: AnalystResearchData): boolean {
+  return data.ratings.some((rating) => (
+    rating.currentPriceTarget != null || rating.priorPriceTarget != null
+  ));
+}
+
+export function isAnalystResearchMissingRatingTargets(data: AnalystResearchData): boolean {
+  return data.ratings.length > 0 && !hasAnalystRatingPriceTargets(data);
+}
+
+export function hasCorporateActionsValue(data: CorporateActionsData): boolean {
+  return data.dividends.length > 0
+    || data.splits.length > 0
+    || data.earnings.length > 0;
+}
+
+function mergeDefinedObject<T extends object>(preferred: T | null | undefined, fallback: T | null | undefined): T | undefined {
+  const mergedEntries: Array<[string, unknown]> = [];
+
+  for (const source of [fallback, preferred]) {
+    if (!source) continue;
+    for (const [key, value] of Object.entries(source)) {
+      if (value !== undefined) {
+        mergedEntries.push([key, value]);
+      }
+    }
+  }
+
+  if (mergedEntries.length === 0) return undefined;
+  return Object.fromEntries(mergedEntries) as T;
+}
+
+export function mergeFinancials(primary: TickerFinancials | null, fallback: TickerFinancials | null): TickerFinancials | null {
+  if (!primary || !fallback) {
+    const single = primary ?? fallback;
+    const resolved = single ? resolveTickerFinancialsQuoteState(normalizeTickerFinancialsPriceHistory(single)) : null;
+    return resolved ? deriveMarketCapFromShares(resolved) : null;
+  }
+
+  const preferFallbackPriceData = hasLikelyQuoteUnitMismatch(primary.quote, fallback.quote);
+  const dominant = preferFallbackPriceData ? fallback : primary;
+  const secondary = preferFallbackPriceData ? primary : fallback;
+  const quoteContributions = mergeQuoteContributionMaps(
+    seedQuoteContributions(primary),
+    seedQuoteContributions(fallback),
+  );
+  const resolvedQuote = resolveCanonicalQuote(quoteContributions).quote;
+
+  return deriveMarketCapFromShares({
+    ...fallback,
+    ...primary,
+    quote: resolvedQuote,
+    quoteContributions,
+    profile: mergeDefinedObject(primary.profile, fallback.profile),
+    fundamentals: mergeDefinedObject(primary.fundamentals, fallback.fundamentals),
+    priceHistory: normalizePriceHistory(dominant.priceHistory.length > 0 ? dominant.priceHistory : secondary.priceHistory),
+    annualStatements: mergeStatementRows(primary.annualStatements, fallback.annualStatements),
+    quarterlyStatements: mergeStatementRows(primary.quarterlyStatements, fallback.quarterlyStatements),
+  });
+}
+
+export function mergeCachedFinancialRecords(
+  records: CachedResourceRecord<TickerFinancials>[],
+  options: { includeStaleQuotes?: boolean } = {},
+): {
+  value: TickerFinancials | null;
+  stale: boolean;
+} {
+  const seenSources = new Set<string>();
+  let merged: TickerFinancials | null = null;
+  let stale = false;
+
+  for (const record of records) {
+    if (seenSources.has(record.sourceKey)) continue;
+    seenSources.add(record.sourceKey);
+    merged = mergeFinancials(merged, sanitizeCachedFinancials(record.value, options));
+    stale = stale || record.stale === true;
+  }
+
+  return { value: merged, stale };
+}
+
+export function selectCachedQuoteRecord(
+  records: CachedResourceRecord<Quote>[],
+  exchange: string | undefined,
+  options: { includeStaleQuotes?: boolean } = {},
+): CachedQuoteSelection {
+  let stale = false;
+
+  for (const record of records) {
+    stale ||= record.stale === true;
+    const quote = sanitizeCachedQuote(record.value, exchange, options);
+    if (quote) return { quote, stale };
+  }
+
+  return { quote: null, stale };
+}