# `Codat.Pagination`
[🔗](https://github.com/iamkanishka/codat.git/blob/v1.0.0/lib/codat/pagination.ex#L1)

Pagination utilities for Codat list endpoints.

All Codat list responses use a `pageNumber` / `pageSize` / `totalResults`
envelope. This module provides a struct, lazy `Stream` pagination, and
concurrent `fetch_all/2`.

# `page_opts`

```elixir
@type page_opts() :: [
  page: pos_integer(),
  page_size: pos_integer(),
  query: String.t(),
  order_by: String.t()
]
```

# `t`

```elixir
@type t() :: %Codat.Pagination{
  has_more?: boolean(),
  page_number: pos_integer(),
  page_size: pos_integer(),
  results: [map()],
  total: non_neg_integer()
}
```

# `default_page_size`

```elixir
@spec default_page_size() :: 100
```

Returns the default page size.

# `fetch_all`

```elixir
@spec fetch_all(
  (pos_integer() -> {:ok, t()} | {:error, Codat.Error.t()}),
  keyword()
) :: {:ok, [map()]} | {:error, Codat.Error.t()}
```

Fetches all pages concurrently and returns a flat list.

## Options

- `:max_concurrency` — max concurrent page fetches (default: 5)
- `:timeout` — per-task timeout in ms (default: 30_000)

# `from_response`

```elixir
@spec from_response(map()) :: t()
```

Wraps a raw Codat list response body into a `%Codat.Pagination{}` struct.

# `stream`

```elixir
@spec stream((pos_integer() -> {:ok, t()} | {:error, Codat.Error.t()})) ::
  Enumerable.t()
```

Returns a lazy `Stream` that fetches pages on demand.

# `stream!`

```elixir
@spec stream!((pos_integer() -> {:ok, t()} | {:error, Codat.Error.t()}), String.t()) ::
  Enumerable.t()
```

Like `stream/1` but raises on error.

# `to_params`

```elixir
@spec to_params(page_opts()) :: keyword()
```

Converts `page_opts` keyword list into Req query params.

---

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