Add pagination support and aggregate API results

[IvanildoBarauna]

Summary

• add reusable pagination iterators and expose pagination strategy metadata on the client
• aggregate paginated responses into DataFetchResult and update documentation with pagination usage
• expand unit test coverage for pagination patterns and DataFetchResult handling

Testing

• poetry run pylint src/api_to_dataframe
• poetry run pytest

---

https://chatgpt.com/codex/tasks/task_e_690ba1452b88832b9e0912eece6a9778

[codecov]

Codecov Report

❌ Patch coverage is 88.23529% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/api_to_dataframe/models/pagination.py	85.29%	15 Missing ⚠️
src/api_to_dataframe/controller/client_builder.py	91.46%	7 Missing ⚠️

📢 Thoughts on this report? Let us know!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Stop cursor pagination when cursor tokens are non‑strings

The new cursor_iterator only extracts the next cursor when the field value is a string. Many cursor-based APIs return integers or opaque objects. In _extract_next_cursor any non-string value is coerced to None, so cursor_iterator immediately breaks at the if next_cursor is None guard even though the response supplied a valid cursor. This causes multi-page APIs with numeric cursors to fetch just the first page and report pages == 1. Consider accepting any JSON-serialisable cursor instead of just strings so pagination can continue for endpoints that use integers.

Useful? React with 👍 / 👎.