tickerapp 0.2.1

Unofficial typed async client for the Ticker.app market data API
Documentation
use std::collections::HashSet;

use crate::{
    DisclosureItem, Error, GetCurrentPriceChangeBasis, GetExchangeResponse, GetTimeseriesKey,
    GetTimeseriesResponse, GetTimeseriesResponseData, ListExchangesResponse,
    ListRnsDisclosureItemsChannel, ListRnsDisclosureItemsResponse, Paging, PriceSnapshot,
    TimeseriesItem, generated::HttpClient,
};

pub const BASE_URL: &str = "https://api.tickerapp.net/v2";

/// One page, using either a cursor or a page number. Defaults are provider-defined.
#[derive(Debug, Clone, Default)]
pub struct PageQuery {
    pub page_size: Option<i64>,
    pub page_cursor: Option<String>,
    pub page_number: Option<i64>,
}

impl PageQuery {
    fn validate(&self) -> Result<(), Error> {
        if self.page_cursor.is_some() && self.page_number.is_some() {
            return Err(Error::InvalidRequest(
                "Choose a page cursor or a page number, not both",
            ));
        }
        if self.page_size.is_some_and(|size| size < 1)
            || self.page_number.is_some_and(|page| page < 1)
        {
            return Err(Error::InvalidRequest(
                "Page size and number must be positive",
            ));
        }
        Ok(())
    }
}

/// Daily history filters. Dates accept the provider's partial ISO8601 syntax.
#[derive(Debug, Clone, Default)]
pub struct TimeseriesQuery {
    pub date_from: Option<String>,
    pub date_to: Option<String>,
    pub include_nav: Option<bool>,
    pub key: Option<GetTimeseriesKey>,
    pub page: PageQuery,
}

/// RNS filters. Responses retain provider warnings about ignored filters.
#[derive(Debug, Clone, Default)]
pub struct DisclosureQuery {
    pub symbols: Vec<String>,
    pub isins: Vec<String>,
    pub date_from: Option<String>,
    pub date_to: Option<String>,
    pub fca_categories: Vec<String>,
    pub ticker_categories: Vec<String>,
    pub query: Option<String>,
    pub has_symbol: Option<bool>,
    pub channel: Option<ListRnsDisclosureItemsChannel>,
    pub page: PageQuery,
}

/// Sends credentials in the x-api-key header. No automatic retries.
#[derive(Clone)]
pub struct Client {
    inner: HttpClient,
}

impl std::fmt::Debug for Client {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Client").finish_non_exhaustive()
    }
}

impl Client {
    pub fn new(api_key: impl Into<String>) -> Self {
        Self {
            inner: HttpClient::new().with_api_key(api_key),
        }
    }

    /// Override the complete API root, including /v2.
    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
        self.inner = self
            .inner
            .with_base_url(base_url.into().trim_end_matches('/'));
        self
    }

    pub fn with_max_response_body_bytes(mut self, limit: usize) -> Self {
        self.inner = self.inner.with_max_response_body_bytes(limit);
        self
    }

    /// All 14 generated operations from the pinned specification.
    pub fn raw(&self) -> &HttpClient {
        &self.inner
    }

    /// Snapshot for an ISIN or MIC:SYMBOL. Missing fields remain None.
    pub async fn price(&self, identifier: &str) -> Result<PriceSnapshot, Error> {
        self.price_with_change_basis(identifier, None).await
    }

    pub async fn price_with_change_basis(
        &self,
        identifier: &str,
        basis: Option<GetCurrentPriceChangeBasis>,
    ) -> Result<PriceSnapshot, Error> {
        Ok(self.inner.get_current_price(identifier, basis).await?.data)
    }

    /// One page; inspect meta.paging before requesting another page.
    pub async fn timeseries(
        &self,
        identifier: &str,
        query: &TimeseriesQuery,
    ) -> Result<GetTimeseriesResponse, Error> {
        query.page.validate()?;
        Ok(self
            .inner
            .get_timeseries(
                identifier,
                query.date_from.as_deref(),
                query.date_to.as_deref(),
                query.include_nav,
                query.key,
                query.page.page_size,
                query.page.page_cursor.as_deref(),
                query.page.page_number,
            )
            .await?)
    }

    /// Collect cursor pages up to an explicit request limit. Returns an error if
    /// more pages remain at the limit, a cursor repeats, or paging changes mode.
    /// No partial history is returned as if it were complete. Row order is kept.
    pub async fn all_timeseries(
        &self,
        identifier: &str,
        query: &TimeseriesQuery,
        max_pages: usize,
    ) -> Result<Vec<TimeseriesItem>, Error> {
        collect_pages(query.page.clone(), max_pages, |page| {
            let query = TimeseriesQuery {
                page,
                ..query.clone()
            };
            async move {
                let response = self.timeseries(identifier, &query).await?;
                Ok((timeseries_items(response.data)?, response.meta.paging))
            }
        })
        .await
    }

    /// One page of disclosures, including warnings and pagination metadata.
    pub async fn disclosures(
        &self,
        query: &DisclosureQuery,
    ) -> Result<ListRnsDisclosureItemsResponse, Error> {
        query.page.validate()?;
        Ok(self
            .inner
            .list_rns_disclosure_items(
                query.date_from.as_deref(),
                query.date_to.as_deref(),
                joined(&query.isins),
                None,
                joined(&query.symbols),
                None,
                joined(&query.fca_categories),
                None,
                joined(&query.ticker_categories),
                None,
                query.query.as_deref(),
                query.page.page_size,
                query.page.page_cursor.as_deref(),
                query.page.page_number,
                query.has_symbol,
                query.channel,
            )
            .await?)
    }

    /// Fetch an individual disclosure by its provider identifier.
    pub async fn disclosure(&self, identifier: &str) -> Result<DisclosureItem, Error> {
        Ok(self.inner.get_rns_disclosure_item(identifier).await?.data)
    }

    pub async fn exchanges(&self, query: &PageQuery) -> Result<ListExchangesResponse, Error> {
        query.validate()?;
        Ok(self
            .inner
            .list_exchanges(
                query.page_size,
                query.page_cursor.as_deref(),
                query.page_number,
            )
            .await?)
    }

    pub async fn exchange(&self, mic: &str) -> Result<GetExchangeResponse, Error> {
        Ok(self.inner.get_exchange(mic).await?)
    }
}

fn joined(values: &[String]) -> Option<String> {
    (!values.is_empty()).then(|| values.join(","))
}

/// Collect rows across cursor pages, starting from `page`. `fetch` requests one page
/// and returns its rows and paging, so callers can send each request through their own
/// retries, pacing or logging; [`Client::all_timeseries`] uses it with
/// [`Client::timeseries`].
///
/// Returns [`Error::InvalidRequest`] for a numbered page or a zero limit, and
/// [`Error::Pagination`] when a cursor repeats or is empty, the provider switches to
/// numbered pages, or more pages remain after `max_pages`. No partial result is
/// returned as if it were complete. Row order is kept.
pub async fn collect_pages<T, E, F, Fut>(
    page: PageQuery,
    max_pages: usize,
    mut fetch: F,
) -> Result<Vec<T>, E>
where
    F: FnMut(PageQuery) -> Fut,
    Fut: Future<Output = Result<(Vec<T>, Paging), E>>,
    E: From<Error>,
{
    if max_pages == 0 || page.page_number.is_some() {
        return Err(Error::InvalidRequest(
            "Use cursor pagination and a positive maximum page count",
        )
        .into());
    }
    let mut page = page;
    let mut seen = HashSet::new();
    if let Some(cursor) = &page.page_cursor {
        seen.insert(cursor.clone());
    }
    let mut rows = Vec::new();
    for _ in 0..max_pages {
        let (items, paging) = fetch(page.clone()).await?;
        rows.extend(items);
        match paging {
            Paging::CursorPaging(paging) => match paging.next_cursor {
                None => return Ok(rows),
                Some(cursor) if !cursor.is_empty() && seen.insert(cursor.clone()) => {
                    page.page_cursor = Some(cursor);
                }
                Some(_) => return Err(Error::Pagination("Repeated or empty cursor").into()),
            },
            Paging::ClassicPaging(_) => {
                return Err(Error::Pagination("Expected cursor pagination").into());
            }
        }
    }
    Err(Error::Pagination("Page limit reached while more pages remain").into())
}

/// Convert array, ISO-date-keyed or Unix-seconds-keyed history into rows.
/// Invalid keys fail explicitly; rows are never silently discarded.
pub fn timeseries_items(data: GetTimeseriesResponseData) -> Result<Vec<TimeseriesItem>, Error> {
    match data {
        GetTimeseriesResponseData::TimeseriesArray(rows) => Ok(rows),
        GetTimeseriesResponseData::GetTimeseriesResponseDataVariant2(keyed) => keyed
            .additional_properties
            .into_iter()
            .map(|(key, row)| {
                let date = chrono::NaiveDate::parse_from_str(&key, "%Y-%m-%d")
                    .ok()
                    .or_else(|| {
                        key.parse::<i64>()
                            .ok()
                            .and_then(|seconds| chrono::DateTime::from_timestamp(seconds, 0))
                            .map(|timestamp| timestamp.date_naive())
                    })
                    .ok_or_else(|| Error::Decode(format!("Invalid timeseries date key: {key}")))?;
                Ok(TimeseriesItem {
                    date,
                    open: row.open,
                    high: row.high,
                    low: row.low,
                    close: row.close,
                    volume: row.volume,
                    nav: row.nav,
                })
            })
            .collect(),
    }
}