fix(backend): BAPIClients list methods should return { data, totalCount }

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */

.changeset/curvy-chefs-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': major
+---
+
+Make all listing API requests to return consistent `{ data: Resource[], totalCount: number }`.

.changeset/healthy-eyes-marry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/types': patch
+---
+
+Fix using `ClerkPaginationRequest` type without passing a generic.
+
+Before the fix the `ClerkPaginationRequest = any` and after the fix the `ClerkPaginationRequest = { limit, offset }`.

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

@@ -47,21 +47,35 @@ export default (QUnit: QUnit) => {
  );
  });
 
- test('executes a successful backend API request for a list of resources and parses the response', async assert => {
+ test('executes 2 backend API request for users.getUserList()', async assert => {
  fakeFetch = sinon.stub(runtime, 'fetch');
  fakeFetch.onCall(0).returns(jsonOk([userJson]));
+ // use different total_count from data in the 1st response to assert that this value is returned from method
+ fakeFetch.onCall(1).returns(jsonOk({ object: 'total_count', total_count: 2 }));
 
- const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+ const { data, totalCount } = await apiClient.users.getUserList({
+ offset: 2,
+ limit: 5,
+ userId: ['user_cafebabe'],
+ });
 
- assert.equal(response[0].firstName, 'John');
- assert.equal(response[0].lastName, 'Doe');
- assert.equal(response[0].emailAddresses[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
- assert.equal(response[0].externalAccounts[0].emailAddress, 'john.doe@clerk.test');
- assert.equal(response[0].publicMetadata.zodiac_sign, 'leo');
+ assert.equal(data[0].firstName, 'John');
+ assert.equal(data[0].id, 'user_cafebabe');
+ assert.equal(data.length, 1);
+ assert.equal(totalCount, 2);
 
  assert.ok(
- fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
+ fakeFetch.calledWith('https://api.clerk.test/v1/users?offset=2&limit=5&user_id=user_cafebabe', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'User-Agent': '@clerk/backend@0.0.0-test',
+ },
+ }),
+ );
+ assert.ok(
+ fakeFetch.calledWith('https://api.clerk.test/v1/users/count?user_id=user_cafebabe', {
  method: 'GET',
  headers: {
  Authorization: 'Bearer deadbeef',

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

@@ -1,5 +1,6 @@
 import { joinPaths } from '../../util/path';
 import type { AllowlistIdentifier } from '../resources/AllowlistIdentifier';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/allowlist_identifiers';
@@ -11,7 +12,7 @@ type AllowlistIdentifierCreateParams = {
 
 export class AllowlistIdentifierAPI extends AbstractAPI {
  public async getAllowlistIdentifierList() {
- return this.request<AllowlistIdentifier[]>({
+ return this.request<PaginatedResourceResponse<AllowlistIdentifier[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,14 +1,18 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { Client } from '../resources/Client';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/clients';
 
 export class ClientAPI extends AbstractAPI {
- public async getClientList() {
- return this.request<Client[]>({
+ public async getClientList(params: ClerkPaginationRequest = {}) {
+ return this.request<PaginatedResourceResponse<Client[]>>({
  method: 'GET',
  path: basePath,
+ queryParams: params,
  });
  }
 

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Invitation } from '../resources/Invitation';
 import { AbstractAPI } from './AbstractApi';
 
@@ -29,7 +30,7 @@ type GetInvitationListParams = {
 
 export class InvitationAPI extends AbstractAPI {
  public async getInvitationList(params: GetInvitationListParams = {}) {
- return this.request<Invitation[]>({
+ return this.request<PaginatedResourceResponse<Invitation[]>>({
  method: 'GET',
  path: basePath,
  queryParams: params,

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

@@ -1,4 +1,5 @@
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { RedirectUrl } from '../resources/RedirectUrl';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,7 +11,7 @@ type CreateRedirectUrlParams = {
 
 export class RedirectUrlAPI extends AbstractAPI {
  public async getRedirectUrlList() {
- return this.request<RedirectUrl[]>({
+ return this.request<PaginatedResourceResponse<RedirectUrl[]>>({
  method: 'GET',
  path: basePath,
  });

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

@@ -1,24 +1,25 @@
-import type { SessionStatus } from '@clerk/types';
+import type { ClerkPaginationRequest, SessionStatus } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { Session } from '../resources/Session';
 import type { Token } from '../resources/Token';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/sessions';
 
-type QueryParams = {
+type SessionListParams = ClerkPaginationRequest<{
  clientId?: string;
  userId?: string;
  status?: SessionStatus;
-};
+}>;
 
 export class SessionAPI extends AbstractAPI {
- public async getSessionList(queryParams?: QueryParams) {
- return this.request<Session[]>({
+ public async getSessionList(params: SessionListParams = {}) {
+ return this.request<PaginatedResourceResponse<Session[]>>({
  method: 'GET',
  path: basePath,
- queryParams: queryParams,
+ queryParams: params,
  });
  }
 

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

@@ -108,11 +108,19 @@ type VerifyTOTPParams = {
 
 export class UserAPI extends AbstractAPI {
  public async getUserList(params: UserListParams = {}) {
- return this.request<User[]>({
- method: 'GET',
- path: basePath,
- queryParams: params,
- });
+ const { limit, offset, orderBy, ...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
+ const [data, totalCount] = await Promise.all([
+ this.request<User[]>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ }),
+ this.getCount(userCountParams),
+ ]);
+ return { data, totalCount } as PaginatedResourceResponse<User[]>;
  }
 
  public async getUser(userId: string) {
@@ -172,7 +180,7 @@ export class UserAPI extends AbstractAPI {
  });
  }
 
- public async getCount(params: UserListParams = {}) {
+ public async getCount(params: UserCountParams = {}) {
  return this.request<number>({
  method: 'GET',
  path: joinPaths(basePath, 'count'),
@@ -182,7 +190,7 @@ export class UserAPI extends AbstractAPI {
 
  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
  this.requireId(userId);
- return this.request<OauthAccessToken[]>({
+ return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
  method: 'GET',
  path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
  });

packages/clerk-js/src/core/fapiClient.ts

@@ -9,7 +9,7 @@ export type HTTPMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PA
 
 export type FapiRequestInit = RequestInit & {
  path?: string;
- search?: string | URLSearchParams | string[][] | Record<string, string | string[]> | undefined;
+ search?: ConstructorParameters<typeof URLSearchParams>[0];
  sessionId?: string;
  rotatingTokenNonce?: string;
  pathPrefix?: string;
@@ -92,7 +92,7 @@ export function createFapiClient(clerkInstance: Clerk): FapiClient {
  return true;
  }
 
- function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit) {
+ function buildQueryString({ method, path, sessionId, search, rotatingTokenNonce }: FapiRequestInit): string {
  const searchParams = new URLSearchParams(search as any);
  // the above will parse {key: ['val1','val2']} as key: 'val1,val2' and we need to recreate the array bellow
 

packages/clerk-js/src/core/resources/Organization.ts

@@ -25,8 +25,8 @@ import type {
  UpdateOrganizationParams,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -87,7 +87,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/roles`,
  method: 'GET',
- search: convertPageToOffset(getRolesParams),
+ search: convertPageToOffsetSearchParams(getRolesParams),
  },
  {
  forceUpdateClient: true,
@@ -109,7 +109,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/domains`,
  method: 'GET',
- search: convertPageToOffset(getDomainParams),
+ search: convertPageToOffsetSearchParams(getDomainParams),
  },
  {
  forceUpdateClient: true,
@@ -140,7 +140,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  return await BaseResource._fetch({
  path: `/organizations/${this.id}/membership_requests`,
  method: 'GET',
- search: convertPageToOffset(getRequestParam),
+ search: convertPageToOffsetSearchParams(getRequestParam),
  }).then(res => {
  const { data: requests, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipRequestJSON>;
@@ -162,7 +162,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...getMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...getMembershipsParams, paginated: true }),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationMembershipJSON>;
@@ -181,7 +181,7 @@ export class Organization extends BaseResource implements OrganizationResource {
  {
  path: `/organizations/${this.id}/invitations`,
  method: 'GET',
- search: convertPageToOffset(getInvitationsParams),
+ search: convertPageToOffsetSearchParams(getInvitationsParams),
  },
  {
  forceUpdateClient: true,

packages/clerk-js/src/core/resources/OrganizationMembership.ts

@@ -8,8 +8,8 @@ import type {
  OrganizationPermissionKey,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { clerkUnsupportedReloadMethod } from '../errors';
 import { BaseResource, Organization, PublicUserData } from './internal';
 
@@ -34,7 +34,7 @@ export class OrganizationMembership extends BaseResource implements Organization
  method: 'GET',
  // `paginated` is used in some legacy endpoints to support clerk paginated responses
  // The parameter will be dropped in FAPI v2
- search: convertPageToOffset({ ...retrieveMembershipsParams, paginated: true }),
+ search: convertPageToOffsetSearchParams({ ...retrieveMembershipsParams, paginated: true }),
  }).then(res => {
  // TODO: Fix typing
  const { data: suggestions, total_count } =

packages/clerk-js/src/core/resources/OrganizationSuggestion.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './Base';
 
 export class OrganizationSuggestion extends BaseResource implements OrganizationSuggestionResource {
@@ -29,7 +29,7 @@ export class OrganizationSuggestion extends BaseResource implements Organization
  return await BaseResource._fetch({
  path: '/me/organization_suggestions',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: suggestions, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<OrganizationSuggestionJSON>;

packages/clerk-js/src/core/resources/UserOrganizationInvitation.ts

@@ -7,8 +7,8 @@ import type {
  UserOrganizationInvitationResource,
 } from '@clerk/types';
 
+import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { convertPageToOffset } from '../../utils/pagesToOffset';
 import { BaseResource } from './internal';
 
 export class UserOrganizationInvitation extends BaseResource implements UserOrganizationInvitationResource {
@@ -27,7 +27,7 @@ export class UserOrganizationInvitation extends BaseResource implements UserOrga
  return await BaseResource._fetch({
  path: '/me/organization_invitations',
  method: 'GET',
- search: convertPageToOffset(params),
+ search: convertPageToOffsetSearchParams(params),
  }).then(res => {
  const { data: invites, total_count } =
  res?.response as unknown as ClerkPaginatedResponse<UserOrganizationInvitationJSON>;

packages/clerk-js/src/utils/convertPageToOffsetSearchParams.ts

@@ -0,0 +1,16 @@
+import { getNonUndefinedValues } from '@clerk/shared';
+import type { ClerkPaginationParams } from '@clerk/types';
+
+export function convertPageToOffsetSearchParams<T>(pageParams: ClerkPaginationParams<T> | undefined) {
+ const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
+ const _pageSize = pageSize ?? 10;
+ const _initialPage = initialPage ?? 1;
+
+ const obj = {
+ ...getNonUndefinedValues(restParams),
+ limit: _pageSize + '',
+ offset: (_initialPage - 1) * _pageSize + '',
+ };
+
+ return new URLSearchParams(obj);
+}

packages/types/src/pagination.ts

@@ -1,7 +1,7 @@
 /**
  * Pagination params in request
  */
-export type ClerkPaginationRequest<T = any> = {
+export type ClerkPaginationRequest<T = object> = {
  /**
  * Maximum number of items returned per request.
  */
@@ -23,7 +23,7 @@ export interface ClerkPaginatedResponse<T> {
 /**
  * Pagination params passed in FAPI client methods
  */
-export type ClerkPaginationParams<T = any> = {
+export type ClerkPaginationParams<T = object> = {
  /**
  * This is the starting point for your fetched results.
  */