Make pagination consistent (use next cursor everywhere)

[ryanio]

Standardize pagination to use next cursors across CLI + SDK

Summary

• CLI: Updated tokens trending and tokens top to use --next <cursor> instead of --cursor <cursor> (to match all other paginated commands). Internally still sends the server query param as cursor.
• SDK: Updated TokensAPI.trending() / TokensAPI.top() options to accept { next?: string } (instead of { cursor?: string }) and map next → cursor in the request params.
• Types: Removed unused PaginatedResponse<T> type since SDK response shapes vary by endpoint key (nfts, listings, offers, etc.).
• Docs: Updated CLI/SDK pagination docs to reflect --next everywhere and documented that search commands don’t expose cursor-based pagination.
• Version: Bumped @opensea/cli minor version 0.2.1 → 0.3.0.
• Tests: Updated/added tests covering the new CLI flag and SDK next → cursor mapping.

Review & Testing Checklist for Human

• Confirm tokens CLI pagination works as intended: opensea tokens trending --limit 5 --next "<cursor>" fetches the next page (and that the outgoing query param is still cursor).
• Confirm SDK pagination works: client.tokens.trending({ next: "<cursor>" }) / top({ next: "<cursor>" }) correctly advances pages.
• Sanity-check docs for any remaining references to --cursor / cursor as the public pagination option (especially around tokens + pagination docs).

Notes

• This is a breaking interface change (CLI flag + SDK option rename), hence the minor version bump.
• Link to Devin run: https://app.devin.ai/sessions/323873ce874140f58eefd24613c6e874
• Requested by: @ryanio

---

[devin-ai-integration]

Original prompt from Ryan

Make pagination consistent across opensea-cli (ProjectOpenSea/opensea-cli). pull latest main.

There are several pagination inconsistencies in the package that should be unified:

1. CLI flag naming mismatch

Most commands use --next <cursor> for pagination, but tokens trending and tokens top use --cursor <cursor>. Standardize all commands to use --next <cursor>.
2. SDK option naming mismatch

Most SDK methods accept { next?: string } for pagination, but TokensAPI.trending() and TokensAPI.top() accept { cursor?: string }. Standardize to next everywhere. The underlying API param sent to the server can remain cursor for the tokens endpoints — just map next → cursor internally like other endpoints do with their param names.
3. Unused PaginatedResponse<T> type

src/types/api.ts defines PaginatedResponse<T> with { next?: string; results: T[] } but it's never used anywhere. Each SDK method defines its own inline return type (e.g. Promise<{ nfts: NFT[]; next?: string }>). Evaluate whether PaginatedResponse<T> can replace the inline types, or remove it if the response shapes are too varied (the array key name differs per endpoint: nfts, listings, offers, tokens, asset_events, collections).
4. Search commands have no pagination

The SearchAPI methods (collections, nfts, tokens, accounts) return bare arrays with no cursor. The GraphQL queries in src/queries.ts don't request any pagination fields. If the GraphQL API supports cursor-based pagination, add it. If not, document this limitation.
5. Update docs

After making changes, update README.md and docs/ to reflect the new consistent pagination interface.
Make sure all existing tests pass and add/update tests for any changed behavior. Run npm run lint, npm run format, and npm run test before creating the PR.

also bump package.json by minor

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.