# `Tipalti.Pagination`
[🔗](https://github.com/iamkanishka/tipalti/blob/main/lib/tipalti/pagination.ex#L1)

Builds lazy `Stream`s over paginated list endpoints so callers can
`Enum.take/2`, pipe into `Enum.reduce/3`, etc. without manually tracking
page cursors.

This isn't tied to any one API family's pagination shape — every
`list`/`stream` pair in this package is built by supplying a `fetch_page`
function of type `(cursor :: term()) -> {:ok, items :: [term()], next_cursor :: term() | nil} |
{:error, Exception.t()}`.

# `fetch_page`

```elixir
@type fetch_page() :: (term() ->
                   {:ok, [term()], term() | nil} | {:error, Exception.t()})
```

# `stream`

```elixir
@spec stream(term(), fetch_page()) :: Enumerable.t()
```

Returns a `Stream` that lazily fetches successive pages via `fetch_page`,
starting from `initial_cursor` (typically `nil`), and yields items one at
a time. If a page fetch fails, the exception is raised into the stream
consumer (mirroring `Enum`'s convention of raising rather than smuggling
`{:error, _}` tuples through a lazy enumerable).

---

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