import type { PriceBasis } from "./instrument";

export type MarketState = "PRE" | "REGULAR" | "POST" | "PREPRE" | "POSTPOST" | "CLOSED";
export type SessionConfidence = "explicit" | "derived" | "unknown";
export type QuoteDataSource = "live" | "delayed" | "snapshot";
export type QuoteDelivery = "stream" | "poll";

export interface QuoteFieldProvenance {
  providerId: string;
  dataSource?: QuoteDataSource;
}

export interface QuoteProvenance {
  price?: QuoteFieldProvenance;
  session?: QuoteFieldProvenance;
  listing?: QuoteFieldProvenance;
  routing?: QuoteFieldProvenance;
  descriptive?: QuoteFieldProvenance;
  fields?: Record<string, QuoteFieldProvenance>;
  rejectedPriceProviders?: string[];
}

/** Static listing facts from a quote observation, without an investable price. */
export interface QuoteMetadataSource {
  providerId?: string;
  lastUpdated?: number;
  stale?: boolean;
  provenance?: QuoteProvenance;
}

export interface QuoteMetadata {
  symbol: string;
  currency?: string;
  instrumentType?: string;
  listingExchangeName?: string;
  source: QuoteMetadataSource;
  /** Overrides only when a missing field was supplied by another observation. */
  fieldSources?: Partial<Record<"currency" | "instrumentType", QuoteMetadataSource>>;
}

export interface Quote {
  /** Applies to this price observation; a stored position cannot supply it. */
  priceBasis?: PriceBasis;
  symbol: string;
  /** Provider-reported security type, independent of the company profile. */
  instrumentType?: string;
  providerId?: string;
  price: number;
  currency: string;
  /** Source units per `currency` unit when the venue quotes a sub-unit, such as 100 for a London line in pence. */
  providerPriceDivisor?: number;
  change: number;
  changePercent: number;
  previousClose?: number;
  /** Official close of a completed regular session, in this quote's currency. */
  regularClose?: number;
  /** Exchange-local date of regularClose; separate from the daily previous-close reference. */
  regularCloseSessionDate?: string;
  /** Provider's exchange-local session date for the daily quote reference. */
  changeSessionDate?: string;
  high52w?: number;
  low52w?: number;
  marketCap?: number;
  volume?: number;
  name?: string;
  lastUpdated: number; // timestamp ms
  receivedAt?: number; // local receipt timestamp ms for streamed/display freshness
  delivery?: QuoteDelivery;
  stale?: boolean;
  exchangeName?: string;
  fullExchangeName?: string;
  listingExchangeName?: string;
  listingExchangeFullName?: string;
  routingExchangeName?: string;
  routingExchangeFullName?: string;
  marketState?: MarketState;
  sessionConfidence?: SessionConfidence;
  preMarketPrice?: number;
  preMarketChange?: number;
  preMarketChangePercent?: number;
  postMarketPrice?: number;
  postMarketChange?: number;
  postMarketChangePercent?: number;
  bid?: number;
  ask?: number;
  bidSize?: number;
  askSize?: number;
  open?: number;
  high?: number;
  low?: number;
  mark?: number;
  /** Executed trade, separate from a midpoint or indicative mark. */
  lastTradePrice?: number;
  /** Timestamp of that trade in milliseconds. */
  lastTradeTime?: number;
  provenance?: QuoteProvenance;
  /** Freshness class for the quote data. Provider identity lives in providerId/provenance. */
  dataSource?: QuoteDataSource;
}

export interface QuoteContribution extends Quote {
  providerId: string;
}

export type QuoteContributionMap = Record<string, QuoteContribution>;

export interface Fundamentals {
  source?: "twelvedata" | "yahoo";
  fetchedAt?: string;
  stale?: boolean;
  /** Currency of reported revenue, income, and cash flows; may differ from the listing. */
  financialCurrency?: string;
  /** Provider-reported issuer market cap; marketCapCurrency identifies its units when known. */
  marketCap?: number;
  marketCapCurrency?: string;
  trailingPE?: number;
  forwardPE?: number;
  /**
   * Forward EPS behind `forwardPE`, per share in the listing's major currency
   * unit. Served only when its basis matches the multiple, so the multiple can
   * be repriced from a live quote; absent otherwise.
   */
  forwardEps?: number;
  pegRatio?: number;
  enterpriseValue?: number;
  enterpriseToRevenue?: number;
  /** Explicit provider retractions; omitted fields alone remain eligible for fallback. */
  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue">;
  operatingCashFlow?: number;
  freeCashFlow?: number;
  dividendYield?: number;
  dividendYieldBasis?: "forward" | "trailing";
  dividendYieldSource?: "twelvedata" | "yahoo";
  /**
   * Annual dividend per share behind `dividendYield`, in the listing's major
   * currency unit. Served only when its basis matches the yield, so the yield
   * can be repriced from a live quote; absent otherwise.
   */
  dividendRate?: number;
  revenue?: number;
  netIncome?: number;
  eps?: number;
  operatingMargin?: number;
  profitMargin?: number;
  revenueGrowth?: number;
  return1Y?: number;
  return3Y?: number;
  lastQuarterGrowth?: number;
  sharesOutstanding?: number;
}

type HolderOwnerType = "institution" | "fund" | "direct" | "insider";

export interface HolderRecord {
  providerId?: string;
  ownerType: HolderOwnerType;
  name: string;
  reportDate?: string;
  shares?: number;
  value?: number;
  percentHeld?: number;
  changeShares?: number;
  changePercent?: number;
}

interface HolderSummary {
  insidersPercentHeld?: number;
  institutionsPercentHeld?: number;
  institutionsFloatPercentHeld?: number;
  institutionsCount?: number;
}

export interface HolderData {
  providerId?: string;
  symbol: string;
  name?: string;
  currency?: string;
  exchange?: string;
  asOf?: string;
  summary?: HolderSummary;
  holders: HolderRecord[];
}

interface AnalystPriceTarget {
  high?: number;
  median?: number;
  low?: number;
  average?: number;
  current?: number;
  currency?: string;
}

interface AnalystRecommendationTrend {
  period: string;
  strongBuy?: number;
  buy?: number;
  hold?: number;
  sell?: number;
  strongSell?: number;
}

export interface AnalystRatingRecord {
  date: string;
  firm: string;
  action?: string;
  current?: string;
  prior?: string;
  currentPriceTarget?: number;
  priorPriceTarget?: number;
}

export interface AnalystEstimateRecord {
  date: string;
  period: string;
  /** Explicit currency for these estimates; independent of the listing currency. */
  currency?: string;
  analysts?: number;
  average?: number;
  low?: number;
  high?: number;
  yearAgo?: number;
  growth?: number;
}

export interface AnalystResearchData {
  providerId?: string;
  fetchedAt?: string;
  stale?: boolean;
  symbol: string;
  name?: string;
  currency?: string;
  exchange?: string;
  micCode?: string;
  exchangeTimezone?: string;
  priceTarget?: AnalystPriceTarget;
  recommendationRating?: number;
  recommendations: AnalystRecommendationTrend[];
  ratings: AnalystRatingRecord[];
  earningsEstimates: AnalystEstimateRecord[];
  revenueEstimates: AnalystEstimateRecord[];
}

export interface DividendAction {
  exDate: string;
  amount: number;
}

export interface SplitAction {
  date: string;
  description?: string;
  /** Provider adjustment ratio; may represent a split or a spinoff price adjustment, not verified share terms. */
  ratio?: number;
  /** Denominator of the provider adjustment factor. */
  fromFactor?: number;
  /** Numerator of the provider adjustment factor. */
  toFactor?: number;
}

export interface EarningsAction {
  date: string;
  dateType?: "announcement" | "fiscal-period-end";
  currency?: string;
  time?: string;
  epsEstimate?: number;
  epsActual?: number;
  difference?: number;
  surprisePercent?: number;
}

export interface CorporateActionsData {
  providerId?: string;
  fetchedAt?: string;
  stale?: boolean;
  coverage?: Partial<Record<"dividends" | "splits" | "earnings", "available" | "unavailable">>;
  symbol: string;
  name?: string;
  currency?: string;
  exchange?: string;
  micCode?: string;
  exchangeTimezone?: string;
  dividends: DividendAction[];
  splits: SplitAction[];
  earnings: EarningsAction[];
}

export interface CompanyProfile {
  description?: string;
  sector?: string;
  industry?: string;
}

export type IncomeStatementField = "netIncome" | "netIncomeIncludingNoncontrollingInterests" | "netIncomeCommonStockholders";

export interface IncomeStatementSource {
  source: "sec";
  concept: string;
  accessionNumber?: string;
  filed?: string;
  startDate?: string;
  endDate: string;
  unit: string;
  basis: "parent" | "consolidated" | "common";
}

export type ReportedOperatingField = "grossProfit" | "operatingExpense" | "operatingIncome";
export type ProviderOperatingField = ReportedOperatingField | "totalExpenses" | "ebitda";

/** Direct reported operating result; every member belongs to one filing cohort. */
export interface ReportedOperatingCohort {
  cik: string;
  period: "annual" | "quarterly";
  startDate: string;
  endDate: string;
  currency: "USD";
  accessionNumber: string;
  filed: string;
  form: string;
  values: Record<ReportedOperatingField, number>;
  anchors?: { totalRevenue?: number; costOfRevenue?: number };
  origin: { kind: "companyfacts" } | {
    kind: "filing-table";
    documentUrl: string;
    documentSha256: string;
    table: "summary-quarterly-results";
    unitScale: 1000000;
  };
}

/** A provider metric is independently owned, not a synonym for a reported subtotal. */
export interface ProviderOperatingObservation {
  provider: "yahoo" | "twelvedata";
  sourceField: string;
  period: "annual" | "quarterly";
  endDate: string;
  currency: string;
  value: number;
}

export interface OperatingResult {
  version: 1;
  reported?: ReportedOperatingCohort;
  provider?: Partial<Record<ProviderOperatingField, ProviderOperatingObservation>>;
  derived?: { ebitda?: DerivedOperatingObservation };
}

export interface DerivedOperatingObservation {
  definition: "operating-income-plus-depreciation-amortization";
  period: "annual" | "quarterly";
  endDate: string;
  currency: string;
  value: number;
  inputs: { operatingIncome: number; depreciationAndAmortization: number };
}

export interface FinancialStatement {
  /** Directly reported annual EPS and its accounting/share-basis evidence. */
  earningsResult?: import("../utils/reported-earnings-result").EarningsResultProvenance;
  /** EPS whose claimed source ownership failed validation; sparse rows cannot restore it. */
  unavailableEarnings?: import("../utils/reported-earnings-result").EarningsField[];
  /** Operating concepts have ownership independent of net income and fiscal dates. */
  operatingResult?: OperatingResult;
  /** Derived operating sums retain their actual quarter inputs, not a single filing owner. */
  operatingResultAggregation?: import("../utils/operating-result-aggregation").OperatingResultAggregation;
  /** Unresolved, source-attested observation withdrawals; identifiers are validated on read. */
  withdrawnObservations?: string[];
  /** SEC EPS share basis; raw source values remain available in the evidence. */
  epsBasis?: import("../utils/sec-eps-basis").SecEpsBasis;
  date: string;
  /** Source of the fiscal period date; does not establish metric publication dates. */
  dateSource?: "sec" | "provider";
  /** Original vendor period date when independent filing evidence changes it. */
  providerDate?: string;
  /** Filing evidence for the period identity only, not availability of every field. */
  dateEvidence?: {
    accessionNumber: string;
    filed: string;
    startDate: string;
  };
  /** Reporting currency for monetary statement fields (per-share values use reported shares). */
  currency?: string;
  /** Earliest date on which the complete row was publicly available, when known. */
  availableAt?: string;
  /** Per-field publication dates used by point-in-time charts and calculations. */
  fieldAvailability?: Record<string, string>;
  /** Income attribution belongs to each field, not to the row's date evidence. */
  fieldSources?: Partial<Record<IncomeStatementField, IncomeStatementSource>>;
  /** Explicit source coverage gaps must not be filled by another income basis. */
  unavailableFields?: IncomeStatementField[];
  // Income Statement
  totalRevenue?: number;
  costOfRevenue?: number;
  grossProfit?: number;
  sellingGeneralAndAdministration?: number;
  researchAndDevelopment?: number;
  operatingExpense?: number;
  operatingIncome?: number;
  operatingRevenue?: number;
  totalExpenses?: number;
  pretaxIncome?: number;
  normalizedIncome?: number;
  netIncomeCommonStockholders?: number;
  netIncomeContinuousOperations?: number;
  otherIncomeExpense?: number;
  otherNonOperatingIncomeExpenses?: number;
  depreciationAmortizationDepletionIncomeStatement?: number;
  depreciationAndAmortizationInIncomeStatement?: number;
  interestExpense?: number;
  taxProvision?: number;
  netIncome?: number;
  netIncomeIncludingNoncontrollingInterests?: number;
  ebitda?: number;
  basicEps?: number;
  eps?: number; // diluted
  basicShares?: number;
  dilutedShares?: number;
  // Cash Flow
  operatingCashFlow?: number;
  depreciationAndAmortization?: number;
  depreciationAmortizationDepletion?: number;
  depreciation?: number;
  deferredIncomeTax?: number;
  deferredTax?: number;
  stockBasedCompensation?: number;
  otherNonCashItems?: number;
  changeInWorkingCapital?: number;
  changeInReceivables?: number;
  changeInInventory?: number;
  changeInPayable?: number;
  changeInAccountPayable?: number;
  changeInOtherWorkingCapital?: number;
  capitalExpenditure?: number;
  cashFlowFromContinuingOperatingActivities?: number;
  interestPaidSupplementalData?: number;
  incomeTaxPaidSupplementalData?: number;
  purchaseOfPPE?: number;
  saleOfPPE?: number;
  netPPEPurchaseAndSale?: number;
  freeCashFlow?: number;
  investingCashFlow?: number;
  cashFlowFromContinuingInvestingActivities?: number;
  purchaseOfBusiness?: number;
  saleOfBusiness?: number;
  netBusinessPurchaseAndSale?: number;
  purchaseOfInvestment?: number;
  saleOfInvestment?: number;
  netInvestmentPurchaseAndSale?: number;
  netOtherInvestingChanges?: number;
  financingCashFlow?: number;
  cashFlowFromContinuingFinancingActivities?: number;
  issuanceOfDebt?: number;
  repaymentOfDebt?: number;
  netIssuancePaymentsOfDebt?: number;
  longTermDebtIssuance?: number;
  longTermDebtPayments?: number;
  netLongTermDebtIssuance?: number;
  shortTermDebtIssuance?: number;
  shortTermDebtPayments?: number;
  netShortTermDebtIssuance?: number;
  repurchaseOfCapitalStock?: number;
  commonStockIssuance?: number;
  commonStockPayments?: number;
  netCommonStockIssuance?: number;
  cashDividendsPaid?: number;
  commonStockDividendPaid?: number;
  netOtherFinancingCharges?: number;
  beginningCashPosition?: number;
  endCashPosition?: number;
  changesInCash?: number;
  effectOfExchangeRateChanges?: number;
  // Balance Sheet
  totalAssets?: number;
  currentAssets?: number;
  cashAndCashEquivalents?: number;
  cashCashEquivalentsAndShortTermInvestments?: number;
  otherShortTermInvestments?: number;
  receivables?: number;
  accountsReceivable?: number;
  inventory?: number;
  prepaidAssets?: number;
  otherCurrentAssets?: number;
  totalNonCurrentAssets?: number;
  netPPE?: number;
  grossPPE?: number;
  accumulatedDepreciation?: number;
  goodwill?: number;
  otherIntangibleAssets?: number;
  goodwillAndOtherIntangibleAssets?: number;
  investmentsAndAdvances?: number;
  otherNonCurrentAssets?: number;
  totalLiabilities?: number;
  currentLiabilities?: number;
  currentDebt?: number;
  currentDebtAndCapitalLeaseObligation?: number;
  payablesAndAccruedExpenses?: number;
  currentAccruedExpenses?: number;
  payables?: number;
  accountsPayable?: number;
  currentDeferredRevenue?: number;
  currentDeferredLiabilities?: number;
  otherCurrentLiabilities?: number;
  totalNonCurrentLiabilities?: number;
  longTermDebt?: number;
  longTermDebtAndCapitalLeaseObligation?: number;
  longTermCapitalLeaseObligation?: number;
  nonCurrentDeferredLiabilities?: number;
  nonCurrentDeferredTaxesLiabilities?: number;
  otherNonCurrentLiabilities?: number;
  totalDebt?: number;
  capitalLeaseObligations?: number;
  totalCapitalization?: number;
  totalEquity?: number;
  totalEquityGrossMinorityInterest?: number;
  commonStockEquity?: number;
  commonStock?: number;
  capitalStock?: number;
  additionalPaidInCapital?: number;
  treasuryStock?: number;
  gainsLossesNotAffectingRetainedEarnings?: number;
  otherEquityAdjustments?: number;
  retainedEarnings?: number;
  longTermEquityInvestment?: number;
  workingCapital?: number;
  netTangibleAssets?: number;
  investedCapital?: number;
  tangibleBookValue?: number;
  shareIssued?: number;
  ordinarySharesNumber?: number;
  treasurySharesNumber?: number;
}

/** Verified provider identity retained with observations through cache/clipping. */
export interface PriceHistorySource {
  provider: "yahoo" | "twelvedata";
  symbol: "SHEL";
  exchange: "LSE";
  currency: "GBP";
  /** Source coverage restriction, not security inception or an adjustment ratio. */
  verifiedLineageStart?: "2005-07-21";
}

export interface PricePoint {
  historySource?: PriceHistorySource;
  date: Date;
  open?: number;
  high?: number;
  low?: number;
  close: number;
  volume?: number;
}

export interface StatementHistoryAttempt {
  mode: "extended";
  source: "sec";
  status: "available" | "unsupported" | "retryable-failure";
  fetchedAt: string;
  attemptedAt?: string;
  cik?: string;
  reason?: string;
}

/** Consensus EPS for one reported quarter as it stood at the report. */
export interface ReportedEpsEstimate {
  /** Announcement date. A row without an actual is an upcoming report. */
  date: string;
  epsEstimate?: number;
  epsActual?: number;
}

export type ConsensusPeriod = "current quarter" | "next quarter" | "current year" | "next year";

/** Today's consensus for a period still open. */
export interface ConsensusEpsEstimate {
  period: ConsensusPeriod | string;
  /** Fiscal period end. */
  date: string;
  average?: number;
  analysts?: number;
  currency?: string;
}

/** One day's observation of the consensus for a period, recorded by the cloud. */
export interface ConsensusEpsSnapshot {
  observedOn: string;
  period: ConsensusPeriod | string;
  periodEnd?: string;
  epsAverage?: number;
  analysts?: number;
  source: string;
}

/**
 * The inputs behind a forward multiple history. Providers only serve today's
 * consensus, so the past is the pre-report consensus per quarter plus whatever
 * the cloud has recorded day by day since it started observing the listing.
 */
export interface EpsEstimateHistory {
  fetchedAt?: string;
  currency?: string;
  reported: ReportedEpsEstimate[];
  consensus: ConsensusEpsEstimate[];
  snapshots: ConsensusEpsSnapshot[];
}

export interface TickerFinancials {
  statementHistory?: StatementHistoryAttempt;
  /** SEC operating-table retry deadline; cache eligibility, not a financial observation. */
  operatingHistoryRetryAt?: number;
  /** Optional annual EPS acquisition retry; independent of statement-history coverage. */
  earningsHistoryRetryAt?: number;
  financialCurrency?: string;
  quote?: Quote;
  quoteMetadata?: QuoteMetadata;
  quoteContributions?: QuoteContributionMap;
  fundamentals?: Fundamentals;
  profile?: CompanyProfile;
  annualStatements: FinancialStatement[];
  quarterlyStatements: FinancialStatement[];
  priceHistory: PricePoint[];
  /** Acquired history cadence. Null explicitly marks an opaque provider default; absent on legacy snapshots. */
  priceHistoryResolution?: import("../time-series/resolution").ManualChartResolution | null;
  /** Stable original acquisition identity, used to replay distinct opaque history windows. */
  priceHistoryRequestKey?: string;
  priceHistorySession?: import("./price-history").HistorySession;
  priceHistorySourceKey?: string;
  /** Present on extended statement history from the cloud. */
  epsEstimates?: EpsEstimateHistory;
}

export interface OptionContract {
  contractSymbol: string;
  strike: number;
  currency: string;
  lastPrice: number;
  change: number;
  percentChange: number;
  /** Missing activity is unknown; an explicitly reported zero remains zero. Yahoo reports an untraded volume as zero. */
  volume?: number;
  openInterest?: number;
  bid: number;
  ask: number;
  impliedVolatility: number;
  inTheMoney: boolean;
  expiration: number;
  lastTradeDate: number;
  /** Millisecond timestamp for the latest streamed quote applied to this snapshot. */
  lastUpdated?: number;
}

export interface OptionsChain {
  underlyingSymbol: string;
  expirationDates: number[];
  calls: OptionContract[];
  puts: OptionContract[];
  providerId?: string;
  dataSource?: "live" | "delayed";
  feed?: "opra" | "yahoo";
  delayMinutes?: number;
  realtimeEligible?: boolean;
  /** ISO timestamp for the upstream options snapshot. */
  asOf?: string;
}