@spec get_asset_profile(String.t()) ::
  {:ok,
   %{
     sector: String.t(),
     industry: String.t() | nil,
     website: String.t() | nil,
     description: String.t() | nil
   }}
  | {:error, error()}

Fetches the company profile for a ticker via Yahoo's quoteSummary endpoint (assetProfile module).

Returns {:ok, %{sector:, industry:, website:, description:}} — industry, website and description may be nil — or {:error, :not_found} for funds, ETFs, and any symbol where Yahoo exposes no asset profile (a blank sector counts as none — matching the Ruby client's behavior). description is Yahoo's longBusinessSummary (English).

@spec get_dividend_history(
  String.t(),
  keyword()
) :: {:ok, [%{date: Date.t(), amount: float()}]} | {:error, error()}

Fetches the per-payment dividend history for a ticker via the chart endpoint's events=div stream.

Returns {:ok, entries} — each entry %{date: Date.t(), amount: float}, sorted ascending by date — or {:ok, []} when the symbol pays no dividends (or Yahoo reports none for the range). Consumers infer payment schedules (frequency, months) from these entries.

Options:

• :range — Yahoo range string, default "2y" (enough to see a quarterly pattern twice).

@spec get_financial_data(String.t()) ::
  {:ok,
   %{
     total_debt: float() | nil,
     debt_to_equity: float() | nil,
     current_ratio: float() | nil,
     quick_ratio: float() | nil,
     total_cash: float() | nil,
     ebitda: float() | nil
   }}
  | {:error, error()}

Fetches key leverage / balance-sheet figures for a ticker via the quoteSummary endpoint (financialData module).

Returns {:ok, %{total_debt, debt_to_equity, current_ratio, quick_ratio, total_cash, ebitda}} — each value a float or nil — or {:error, :not_found} when Yahoo exposes no financialData (common for funds/ETFs and many non-US tickers). debt_to_equity is Yahoo's percentage figure (e.g. 151.4 = 151.4%).

@spec get_fx_rate(String.t(), String.t()) :: {:ok, float()} | {:error, error()}

Fetches the current FX rate between two ISO 4217 currency codes — one unit of from expressed in to.

Returns {:ok, 1.0} for identity pairs without hitting the API. Returns {:ok, rate} (a float) on success, or {:error, reason} on failure (including :not_found when Yahoo has no quote for the pair).

@spec get_news(
  String.t(),
  keyword()
) ::
  {:ok,
   [
     %{
       title: String.t(),
       url: String.t() | nil,
       publisher: String.t() | nil,
       published_at: DateTime.t() | nil
     }
   ]}
  | {:error, error()}

Fetches recent news headlines for a ticker via Yahoo's /v1/finance/search endpoint (its news stream).

Returns {:ok, items} — each %{title:, url:, publisher:, published_at:} with published_at a UTC DateTime (or nil), most-recent first — or {:ok, []} when Yahoo returns no news.

Options:

• :count — max headlines to request, default 8.

@spec get_price_history(
  String.t(),
  keyword()
) :: {:ok, [%{date: Date.t(), close: float()}]} | {:error, error()}

Fetches the monthly closing-price history for a ticker via the chart endpoint (the price series alongside the dividend stream).

Returns {:ok, entries} — each entry %{date: Date.t(), close: float}, sorted ascending by date, skipping months Yahoo reports as null — or {:ok, []} when the symbol has no price data. Consumers use it (paired with the dividend history) to build a historical yield band.

Options:

• :range — Yahoo range string, default "6y" (enough for a ~5-year yield band plus a buffer).

@spec get_quote(String.t()) :: {:ok, YahooFinanceEx.Quote.t()} | {:error, error()}

Fetches a single stock quote.

Returns {:ok, %YahooFinanceEx.Quote{}} on success, or {:error, reason} with one of the error/0 shapes on failure.

Retries once on transient auth errors (Yahoo invalidates sessions occasionally); deeper failures bubble up.

@spec get_quotes([String.t()]) ::
  {:ok, %{required(String.t()) => per_symbol_result()}} | {:error, error()}

Fetches quotes for many symbols in one or more batched HTTP calls.

Returns {:ok, results_map} where results_map is %{symbol => {:ok, Quote.t()} | {:error, :not_found}} — i.e. each requested symbol is present in the map, mapped to its individual result. Symbols Yahoo doesn't recognize come back as {:error, :not_found}.

Top-level errors ({:auth_failed, _}, {:transport, _}, etc.) abort the whole call and are returned as {:error, reason}.

Symbols are batched in groups of 50 (Yahoo's per-request ceiling). Duplicates and empty lists are tolerated.

@spec search(
  String.t(),
  keyword()
) :: {:ok, [search_result()]} | {:error, error()}

Searches Yahoo Finance for tickers matching a free-text query (a ticker fragment or a company name) via the /v1/finance/search autocomplete endpoint.

Returns {:ok, results} — each result %{symbol:, name:, exchange:, type:}, in Yahoo's relevance order — or {:ok, []} for a blank query or no matches. type is Yahoo's quoteType ("EQUITY", "ETF", "MUTUALFUND", "INDEX", …) so callers can filter to the instruments they care about; name falls back shortname → longname → symbol.

Options:

• :count — max results to request, default 10.