Add a paginated response interceptor and type

[EmmanuelOchaje]

Context

Paginated endpoints should share one response shape.

Task

• Add a Paginated type and helper returning items, total, page, limit

Acceptance criteria

• Documented in docs/API.md

This issue is self-contained and can be picked up independently of any other open issue.

[Kami-no-san]

@Kami-no-san has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Good day Maintainer, I have read and understood the requirement for this issue. I will implement the solution and deliver gracefully. Please assign!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Kami-no-san to this issue.

[Adesam007-pr3dator]

@Adesam007-pr3dator has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi, I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Adesam007-pr3dator to this issue.

[OgbuKingsley166]

@OgbuKingsley166 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I’ve resolved similar problems in the past and am confident I can implement a clean, efficient fix quickly,if am given the opportunity.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @OgbuKingsley166 to this issue.

[devgrace100]

@devgrace100 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi maintainer, I'd like to work on this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @devgrace100 to this issue.

[drips-wave]

Congratulations, @devgrace100! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @devgrace100: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊