feat(backend): support cursor pagination in getUserList

.changeset/user-list-cursor-pagination.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `startingAfter` to `users.getUserList()` so applications can page through user lists with a cursor.

packages/backend/src/api/__tests__/factory.test.ts

@@ -68,6 +68,37 @@ describe('api.client', () => {
     expect(totalCount).toBe(2);
   });
 
+  it('sends startingAfter only to the users list request', async () => {
+    server.use(
+      http.get(
+        `https://api.clerk.test/v1/users`,
+        validateHeaders(({ request }) => {
+          const url = new URL(request.url);
+          expect(url.searchParams.get('starting_after')).toBe('user_previous');
+          expect(url.searchParams.has('startingAfter')).toBe(false);
+          return HttpResponse.json([userJson]);
+        }),
+      ),
+      http.get(
+        `https://api.clerk.test/v1/users/count`,
+        validateHeaders(({ request }) => {
+          const url = new URL(request.url);
+          expect(url.searchParams.has('starting_after')).toBe(false);
+          expect(url.searchParams.has('startingAfter')).toBe(false);
+          return HttpResponse.json({ object: 'total_count', total_count: 2 });
+        }),
+      ),
+    );
+
+    const { data, totalCount } = await apiClient.users.getUserList({
+      startingAfter: 'user_previous',
+      orderBy: '-created_at',
+    });
+
+    expect(data[0].id).toBe('user_cafebabe');
+    expect(totalCount).toBe(2);
+  });
+
   it('executes users.getUserList() with last_sign_in_at filters', async () => {
     const afterTimestamp = 1640000000;
     const beforeTimestamp = 1700000000;

packages/backend/src/api/endpoints/UserApi.ts

@@ -38,6 +38,11 @@ export type UserCountParams = {
 
 /** @generateWithEmptyComment */
 export type UserListParams = ClerkPaginationRequest<{
+  /**
+   * The ID of the last user on the previous page. Only valid when `orderBy` is `created_at`, `+created_at`,
+   * or `-created_at` and `offset` is omitted or `0`.
+   */
+  startingAfter?: string;
   /** Filters users with the specified email addresses. Accepts up to 100 email addresses. */
   emailAddress?: string[];
   /** Filters users with the specified phone numbers. Accepts up to 100 phone numbers. */
@@ -435,7 +440,7 @@ export class UserAPI extends AbstractAPI {
    * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [`User`](https://clerk.com/docs/reference/backend/types/backend-user) objects, and a `totalCount` property that indicates the total number of users in your instance.
    */
   public async getUserList(params: UserListParams = {}) {
-    const { limit, offset, orderBy, ...userCountParams } = params;
+    const { limit, offset, orderBy, startingAfter, ...userCountParams } = params;
     // TODO(dimkl): Temporary change to populate totalCount using a 2nd BAPI call to /users/count endpoint
     // until we update the /users endpoint to be paginated in a next BAPI version.
     // In some edge cases the data.length != totalCount due to a creation of a user between the 2 api responses