# `ExOura.Pagination`
[🔗](https://github.com/tgrk/ex_oura/blob/v3.0.1/lib/ex_oura/pagination.ex#L1)

Helper functions for handling paginated responses from Oura API.

This module provides utilities to automatically fetch all pages of data
from paginated endpoints, handling the `next_token` mechanism used by
the Oura API.

# `fetch_all_pages`

```elixir
@spec fetch_all_pages(
  fetch_function :: (Date.t(), Date.t(), String.t() | nil, keyword() ->
                       {:ok, map()} | {:error, any()}),
  start_date :: Date.t(),
  end_date :: Date.t(),
  opts :: keyword()
) :: {:ok, list()} | {:error, any()}
```

Fetches all pages of data from a paginated endpoint.

## Parameters

  * `fetch_fn` - A function that takes (start_date, end_date, next_token, opts)
    and returns {:ok, response} or {:error, reason}
  * `start_date` - The start date for the data range
  * `end_date` - The end date for the data range
  * `opts` - Additional options to pass to the fetch function

## Examples

    iex> fetch_fn = fn start_date, end_date, next_token, opts ->
    ...>   ExOura.multiple_daily_activity(start_date, end_date, next_token, opts)
    ...> end
    iex> ExOura.Pagination.fetch_all_pages(fetch_fn, ~D[2025-01-01], ~D[2025-01-31])
    {:ok, [%{id: "1", ...}, %{id: "2", ...}]}

## Returns

  * `{:ok, data}` - All data from all pages combined into a single list
  * `{:error, reason}` - If any page fetch fails

# `stream_all_pages`

```elixir
@spec stream_all_pages(
  fetch_function :: (Date.t(), Date.t(), String.t() | nil, keyword() ->
                       {:ok, map()} | {:error, any()}),
  start_date :: Date.t(),
  end_date :: Date.t(),
  opts :: keyword()
) :: Enumerable.t()
```

Fetches all pages using a stream for memory efficiency.

This function returns a stream that yields individual data items across
all pages, allowing for memory-efficient processing of large datasets.

## Parameters

  * `fetch_fn` - A function that takes (start_date, end_date, next_token, opts)
  * `start_date` - The start date for the data range
  * `end_date` - The end date for the data range
  * `opts` - Additional options

## Returns

  * `Enumerable.t()` - A stream of individual data items

---

*Consult [api-reference.md](api-reference.md) for complete listing*