feat(pagination): add generic Paginator and public CLOB pagers

[yluoc]

Summary

Each CLOB and Data API list endpoint had its own copy of the paging loop. Errors were handled differently from one to the next, and callers had no way to read one page at a time or resume.

• Adds include/polymarket/pagination.hpp with Paginator<T> for cursor and offset paging. It offers next_page(), collect(max_items), range-for over items with error() checked afterwards, and resume_token(). Items fetched before a failure are kept. A repeated cursor or more than 1000 pages is an error. Reaching the offset cap sets truncated().
• Adds pagers to ClobClient: markets_pager, sampling_markets_pager, simplified_markets_pager, sampling_simplified_markets_pager, open_orders_pager, trades_pager, positions_pager, redeemable_positions_pager and mergeable_positions_pager.
• Moves the existing open-orders, trades, rewards, earnings, positions and MarketFetcher loops onto Paginator. Legacy methods return the same results as before.

Verification

Commands run and their actual results:

• cmake --build build --parallel 2 && ctest --test-dir build --output-on-failure -LE live: 65/65 passed (Linux, Release, GCC 13.3), including test_package_consumer and the two fuzz corpus replay tests.
• python3 scripts/quality.py main --build-dir build: passed.
• New tests: test_pagination (engine, fake fetcher) and test_clob_pagers (pagers against the local HTTP fixture).

Checks not run and the reason (or none):

• macOS and Debug builds: no local environment. Left to CI.
• Live tests (-LE live): only read-only paging changed, and the request URLs are checked by fixture tests.
• libFuzzer runs: no parser changed.
• Benchmarks: no hot path changed.

Compatibility and evidence

Public API, binary compatibility, or release implications (or none):

• Additive only. ClobClient gains methods but no data members, and clob_client.hpp now includes pagination.hpp.
• src/opaque_cursor_pagination.hpp moved into the public header under polymarket::detail, and its constant MAX_PAGES is now max_pages.
• One small behavior difference: when get_open_orders_result hits a repeated cursor, the Parse error no longer carries a response body excerpt.

Not a protocol change. All coverage is local fixtures; no live calls were made.

[SebastianBoehler]

Thanks Bill. Two issues to address before this is ready:

1. GCC build failure (include/polymarket/pagination.hpp:188-191): the free friend operator== defined inside ItemIterator accesses Paginator's private buffer_index_ and buffer_. It does not inherit the nested class's access rights. All three Ubuntu build jobs fail here. Move the private-state check into an ItemIterator member and call that from the comparison, or otherwise provide valid access.

2. Offset resume token repeats the final page (include/polymarket/pagination.hpp:263-267): the short-page and offset-cap branches leave offset_ pointing at the page just fetched. With limit=2 and max_offset=2, collecting pages at offsets 0 and 2 returns resume_token().offset=2; reconstructing a paginator from that token fetches offset 2 again. I reproduced the duplicate locally. The token needs to represent the next position or exhaustion, including both terminal paths, with regression coverage.

The focused paginator tests pass locally with Apple Clang; the GCC failure is confirmed by the CI logs. The resume issue was reproduced with a small deterministic fetcher.

For future PRs, please make sure all required CI checks pass before requesting review. For this PR, please fix the failures and wait for green CI before requesting another review.