Add cursor based pagination

[devkiran]

Summary by CodeRabbit

• New Features

  • Added cursor-based pagination (startingAfter/endingBefore) alongside offset-based pagination and query validation.

• Refactor

  • Centralized pagination logic into a shared helper and updated query schemas to layer cursor pagination with legacy pagination (deprecated).

• Performance

  • Added/updated composite database indexes to improve pagination and time-range queries.

• Tests

  • Added comprehensive pagination tests covering offset, cursor flows, mixed methods, error cases, and sort orders.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
dub	Ready	Preview	Jan 8, 2026 6:45am

[coderabbitai[bot]]

[!WARNING]

Rate limit exceeded

@devkiran has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 38 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between fa9804826908af9ae5f7c4096975103c48f58ab8 and 689b3ff6603ccd9e9e07aec64639857f24a1707f.

📒 Files selected for processing (1)

• apps/web/lib/api/pagination.ts

📝 Walkthrough

Walkthrough

This PR centralizes pagination by adding a reusable getPaginationOptions helper (cursor + offset), updates Zod pagination schemas to expose cursor-based queries (marking offset deprecated), refactors API callsites to use the helper, updates Prisma composite indexes to include id as a tiebreaker, and adds comprehensive pagination tests.

Changes

Cohort / File(s)	Summary
Pagination utility & types apps/web/lib/api/pagination.ts	New getPaginationOptions(filters) plus Filters/PaginationOptions types implementing cursor and offset pagination, validation, and errors.
Zod pagination primitives apps/web/lib/zod/schemas/misc.ts	getPaginationQuerySchema signature changed (optional pageSize, deprecated flag); new getCursorPaginationQuerySchema exported.
Zod schema integrations apps/web/lib/zod/schemas/commissions.ts, apps/web/lib/zod/schemas/customers.ts, apps/web/lib/zod/schemas/links.ts	Schemas now merge getCursorPaginationQuerySchema before existing pagination merge; offset pagination preserved but marked deprecated.
API callsites / endpoints apps/web/app/(ee)/api/customers/route.ts, apps/web/lib/api/commissions/get-commissions.ts, apps/web/lib/api/links/get-links-for-workspace.ts	Replaced manual page/pageSize/sort handling with getPaginationOptions(filters); getLinksForWorkspace signature changed to accept a single filters object.
Database schema / indexes packages/prisma/schema/commission.prisma, packages/prisma/schema/customer.prisma, packages/prisma/schema/link.prisma	Composite indexes updated to include id as a tiebreaker (added/changed to include id).
Tests (pagination) apps/web/tests/commissions/pagination.test.ts, apps/web/tests/customers/pagination.test.ts, apps/web/tests/links/list-links.test.ts	New comprehensive tests covering offset & cursor pagination, invalid combos/limits, mixed-method precedence, deterministic ordering, and cursor behavior.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant API as Web API
  participant Pager as getPaginationOptions
  participant DB as Prisma/Database

  Client->>API: GET /endpoint?{page,pageSize,startingAfter,endingBefore,sortBy,...}
  API->>Pager: getPaginationOptions(filters)
  Pager-->>API: { take, skip } or { cursor, cursorId }, orderBy
  API->>DB: Prisma.findMany({ where: ..., include: ..., ...paginationOptions })
  DB-->>API: results
  API-->>Client: 200 + items

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #3172 — Implements the same cursor+offset pagination refactor and adds getPaginationOptions, cursor pagination schemas, and tests across the same endpoints.
• PR #3182 — Reverts the cursor-based pagination changes introduced by this work (direct conflict candidate).
• PR #3121 — Applies pagination changes to payouts and relies on the updated pagination utilities/schema; touches similar pagination surface.

Suggested reviewers

• steven-tey

Poem

🐰
I hopped through queries with a twitchy nose,
Cursor or page—now everyone knows.
I nudged indexes neat, made order supreme,
Pages hop steady like a carrot dream. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately captures the main change: introducing cursor-based pagination support across multiple API endpoints and schemas.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}