[GH-ISSUE #38] Auto-pagination for list commands #5

New issue

Closed

opened 2026-02-26 21:32:43 +03:00 by kerem · 1 comment

kerem commented

2026-02-26 21:32:43 +03:00

Owner

Originally created by @rudrankriyam on GitHub (Jan 21, 2026).
Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/38

PRD: Auto-pagination for list commands

Summary

Today pagination is manual (--limit + --next). Add opt-in auto-pagination to fetch all pages and return aggregated output for list/collection commands.

Goals

Add a --paginate flag to list/collection commands.
Preserve default behavior (no auto-pagination unless requested).
Respect --limit as page size.
Support JSON/table/markdown outputs with aggregated data.
Provide clear errors when pagination fails midstream.

Non-goals

Changing default pagination behavior or API semantics.
Streaming outputs or partial results mid-request.
Changing analytics get --paginate behavior (separate, already specialized).

Commands in scope

feedback
crashes
reviews
apps
builds list
versions list
localizations list (both appStoreVersion and appInfo)
beta-groups list
beta-testers list
analytics requests
sandbox list

CLI behavior

Add --paginate (bool) to each command above.
If --paginate and --next are both provided: start at --next and continue until links.next is empty.
If --paginate is provided without --next: start from the initial request.
--limit continues to apply per page.
Errors should include which page failed (or the failing next URL).

Output semantics

JSON output: aggregate data across pages into a single response.
- links.self: from the first page
- links.next: empty/omitted in final output
- links.prev: empty/omitted in final output
Table/Markdown: print header once, then all rows across pages.

Implementation plan

Add a shared pagination helper (likely in cmd/commands.go or internal/asc) that:
- accepts a fetch function func(next string) (response, error)
- loops over links.next until empty
- aggregates data and returns a single response
Update list commands to wire --paginate and use the helper when set.
Continue to validate user-provided --next (reuse validateNextURL).

Test plan

Unit tests for pagination helper (multi-page, empty next, error midstream).
Client HTTP tests for at least one endpoint verifying next URL usage.
CLI validation tests for --paginate behavior:
- --paginate without --next
- --paginate with --next
- aggregated output counts

Documentation

Update README.md + Agents.md with --paginate guidance on list commands.
Add at least one help example showing auto-pagination.

Risks / edge cases

Large datasets could increase memory usage; document the trade-off.
Some endpoints may return empty data with links.next still present; continue until next is empty.

Originally created by @rudrankriyam on GitHub (Jan 21, 2026). Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/38 # PRD: Auto-pagination for list commands ## Summary Today pagination is manual (`--limit` + `--next`). Add opt-in auto-pagination to fetch all pages and return aggregated output for list/collection commands. ## Goals - Add a `--paginate` flag to list/collection commands. - Preserve default behavior (no auto-pagination unless requested). - Respect `--limit` as page size. - Support JSON/table/markdown outputs with aggregated data. - Provide clear errors when pagination fails midstream. ## Non-goals - Changing default pagination behavior or API semantics. - Streaming outputs or partial results mid-request. - Changing `analytics get --paginate` behavior (separate, already specialized). ## Commands in scope - `feedback` - `crashes` - `reviews` - `apps` - `builds list` - `versions list` - `localizations list` (both appStoreVersion and appInfo) - `beta-groups list` - `beta-testers list` - `analytics requests` - `sandbox list` ## CLI behavior - Add `--paginate` (bool) to each command above. - If `--paginate` and `--next` are both provided: start at `--next` and continue until `links.next` is empty. - If `--paginate` is provided without `--next`: start from the initial request. - `--limit` continues to apply per page. - Errors should include which page failed (or the failing `next` URL). ## Output semantics - **JSON output:** aggregate `data` across pages into a single response. - `links.self`: from the first page - `links.next`: empty/omitted in final output - `links.prev`: empty/omitted in final output - **Table/Markdown:** print header once, then all rows across pages. ## Implementation plan 1. Add a shared pagination helper (likely in `cmd/commands.go` or `internal/asc`) that: - accepts a fetch function `func(next string) (response, error)` - loops over `links.next` until empty - aggregates `data` and returns a single response 2. Update list commands to wire `--paginate` and use the helper when set. 3. Continue to validate user-provided `--next` (reuse `validateNextURL`). ## Test plan - Unit tests for pagination helper (multi-page, empty `next`, error midstream). - Client HTTP tests for at least one endpoint verifying `next` URL usage. - CLI validation tests for `--paginate` behavior: - `--paginate` without `--next` - `--paginate` with `--next` - aggregated output counts ## Documentation - Update `README.md` + `Agents.md` with `--paginate` guidance on list commands. - Add at least one help example showing auto-pagination. ## Risks / edge cases - Large datasets could increase memory usage; document the trade-off. - Some endpoints may return empty `data` with `links.next` still present; continue until `next` is empty.