chore(types,clerk-js,backend): Re-use common pagination types

.changeset/quick-countries-scream.md

@@ -0,0 +1,12 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/backend': minor
+'@clerk/types': minor
+---
+
+Re-use common pagination types for consistency across types.
+
+Types introduced in `@clerk/types`:
+- `ClerkPaginationRequest` : describes pagination related props in request payload
+- `ClerkPaginatedResponse` : describes pagination related props in response body
+- `ClerkPaginationParams`  : describes pagination related props in api client method params

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

@@ -1,3 +1,5 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import runtime from '../../runtime';
 import { joinPaths } from '../../util/path';
 import type {
@@ -16,12 +18,10 @@ type MetadataParams<TPublic = OrganizationPublicMetadata, TPrivate = Organizatio
   privateMetadata?: TPrivate;
 };
 
-type GetOrganizationListParams = {
-  limit?: number;
-  offset?: number;
+type GetOrganizationListParams = ClerkPaginationRequest<{
   includeMembersCount?: boolean;
   query?: string;
-};
+}>;
 
 type CreateParams = {
   name: string;
@@ -46,11 +46,9 @@ type UpdateLogoParams = {
 
 type UpdateMetadataParams = MetadataParams;
 
-type GetOrganizationMembershipListParams = {
+type GetOrganizationMembershipListParams = ClerkPaginationRequest<{
   organizationId: string;
-  limit?: number;
-  offset?: number;
-};
+}>;
 
 type CreateOrganizationMembershipParams = {
   organizationId: string;
@@ -79,12 +77,10 @@ type CreateOrganizationInvitationParams = {
   publicMetadata?: OrganizationInvitationPublicMetadata;
 };
 
-type GetOrganizationInvitationListParams = {
+type GetOrganizationInvitationListParams = ClerkPaginationRequest<{
   organizationId: string;
   status?: OrganizationInvitationStatus[];
-  limit?: number;
-  offset?: number;
-};
+}>;
 
 type GetOrganizationInvitationParams = {
   organizationId: string;

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

@@ -1,15 +1,15 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { DeletedObject, Permission } from '../resources';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/organizations_permissions';
 
-type GetOrganizationPermissionListParams = {
-  limit?: number;
-  offset?: number;
+type GetOrganizationPermissionListParams = ClerkPaginationRequest<{
   query?: string;
   orderBy?: string;
-};
+}>;
 
 type CreateParams = {
   name: string;

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

@@ -1,15 +1,15 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
 import { joinPaths } from '../../util/path';
 import type { DeletedObject, Role } from '../resources';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/organizations_roles';
 
-type GetRoleListParams = {
-  limit?: number;
-  offset?: number;
+type GetRoleListParams = ClerkPaginationRequest<{
   query?: string;
   order_by?: string;
-};
+}>;
 
 type CreateParams = {
   /**

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

@@ -1,4 +1,4 @@
-import type { OAuthProvider } from '@clerk/types';
+import type { ClerkPaginationRequest, OAuthProvider } from '@clerk/types';
 
 import runtime from '../../runtime';
 import { joinPaths } from '../../util/path';
@@ -17,11 +17,11 @@ type UserCountParams = {
   externalId?: string[];
 };
 
-type UserListParams = UserCountParams & {
-  limit?: number;
-  offset?: number;
-  orderBy?: 'created_at' | 'updated_at' | '+created_at' | '+updated_at' | '-created_at' | '-updated_at';
-};
+type UserListParams = ClerkPaginationRequest<
+  UserCountParams & {
+    orderBy?: 'created_at' | 'updated_at' | '+created_at' | '+updated_at' | '-created_at' | '-updated_at';
+  }
+>;
 
 type UserMetadataParams = {
   publicMetadata?: UserPublicMetadata;
@@ -77,11 +77,9 @@ interface UpdateUserParams extends UserMetadataParams {
   createdAt?: Date;
 }
 
-type GetOrganizationMembershipListParams = {
+type GetOrganizationMembershipListParams = ClerkPaginationRequest<{
   userId: string;
-  limit?: number;
-  offset?: number;
-};
+}>;
 
 type VerifyPasswordParams = {
   userId: string;

packages/clerk-js/src/ui.retheme/components/CreateOrganization/CreateOrganization.tsx

@@ -1,4 +1,4 @@
-import type { CreateOrganizationModalProps, CreateOrganizationProps } from '@clerk/types';
+import type { CreateOrganizationModalProps } from '@clerk/types';
 
 import { withOrganizationsEnabledGuard } from '../../common';
 import { ComponentContext, withCoreUserGuard } from '../../contexts';

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

@@ -1,9 +1,5 @@
-import type { ClerkPaginationParams } from '@clerk/types';
+import type { ClerkPaginationParams, ClerkPaginationRequest } from '@clerk/types';
 
-type Pages = {
-  initialPage?: number;
-  pageSize?: number;
-};
 function getNonUndefinedValues<T>(obj: Record<string, T>): Record<string, T> {
   return Object.keys(obj).reduce((result, key) => {
     if (obj[key] !== undefined) {
@@ -12,8 +8,10 @@ function getNonUndefinedValues<T>(obj: Record<string, T>): Record<string, T> {
     return result;
   }, {} as Record<string, T>);
 }
-export function convertPageToOffset<T extends Pages | undefined>(pageParams: T): ClerkPaginationParams {
-  const { pageSize, initialPage, ...restParams } = pageParams || {};
+export function convertPageToOffset<T extends ClerkPaginationParams | undefined>(
+  pageParams: T,
+): ClerkPaginationRequest {
+  const { pageSize, initialPage, ...restParams } = pageParams || ({} as ClerkPaginationParams);
   const _pageSize = pageSize ?? 10;
   const _initialPage = initialPage ?? 1;
 

packages/types/src/api.ts

@@ -23,19 +23,3 @@ export interface ClerkRuntimeError {
   code: string;
   message: string;
 }
-
-/**
- * Pagination params
- */
-export interface ClerkPaginationParams {
-  limit?: number;
-  offset?: number;
-}
-
-/**
- * Pagination params
- */
-export interface ClerkPaginatedResponse<T> {
-  data: T[];
-  total_count: number;
-}

packages/types/src/index.retheme.ts

@@ -53,3 +53,4 @@ export * from './verification';
 export * from './web3';
 export * from './web3Wallet';
 export * from './customPages';
+export * from './pagination';

packages/types/src/index.ts

@@ -53,3 +53,4 @@ export * from './verification';
 export * from './web3';
 export * from './web3Wallet';
 export * from './customPages';
+export * from './pagination';

packages/types/src/organization.ts

@@ -1,8 +1,8 @@
-import type { ClerkPaginatedResponse } from './api';
 import type { OrganizationDomainResource, OrganizationEnrollmentMode } from './organizationDomain';
 import type { OrganizationInvitationResource, OrganizationInvitationStatus } from './organizationInvitation';
 import type { MembershipRole, OrganizationMembershipResource } from './organizationMembership';
 import type { OrganizationMembershipRequestResource } from './organizationMembershipRequest';
+import type { ClerkPaginatedResponse, ClerkPaginationParams } from './pagination';
 import type { ClerkResource } from './resource';
 import type { RoleResource } from './role';
 
@@ -64,68 +64,23 @@ export interface OrganizationResource extends ClerkResource {
 /**
  * @experimental
  */
-export type GetRolesParams = {
-  /**
-   * This is the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
-};
-
-export type GetMembersParams = {
-  /**
-   * This is the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
+export type GetRolesParams = ClerkPaginationParams;
 
+export type GetMembersParams = ClerkPaginationParams<{
   role?: MembershipRole[];
-};
-
-export type GetDomainsParams = {
-  /**
-   * This is the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
+}>;
 
+export type GetDomainsParams = ClerkPaginationParams<{
   enrollmentMode?: OrganizationEnrollmentMode;
-};
-
-export type GetInvitationsParams = {
-  /**
-   * This is the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
+}>;
 
+export type GetInvitationsParams = ClerkPaginationParams<{
   status?: OrganizationInvitationStatus[];
-};
-
-export type GetMembershipRequestParams = {
-  /**
-   * This is the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
+}>;
 
+export type GetMembershipRequestParams = ClerkPaginationParams<{
   status?: OrganizationInvitationStatus;
-};
+}>;
 
 export interface AddMemberParams {
   userId: string;

packages/types/src/pagination.ts

@@ -0,0 +1,35 @@
+/**
+ * Pagination params in request
+ */
+export type ClerkPaginationRequest<T = any> = {
+  /**
+   * Maximum number of items returned per request.
+   */
+  limit?: number;
+  /**
+   * This is the starting point for your fetched results.
+   */
+  offset?: number;
+} & T;
+
+/**
+ * Pagination params in response
+ */
+export interface ClerkPaginatedResponse<T> {
+  data: T[];
+  total_count: number;
+}
+
+/**
+ * Pagination params passed in FAPI client methods
+ */
+export type ClerkPaginationParams<T = any> = {
+  /**
+   * This is the starting point for your fetched results.
+   */
+  initialPage?: number;
+  /**
+   * Maximum number of items returned per request.
+   */
+  pageSize?: number;
+} & T;

packages/types/src/user.ts

@@ -1,4 +1,3 @@
-import type { ClerkPaginatedResponse } from './api';
 import type { BackupCodeResource } from './backupCode';
 import type { DeletedObjectResource } from './deletedObject';
 import type { EmailAddressResource } from './emailAddress';
@@ -9,6 +8,7 @@ import type { OAuthScope } from './oauth';
 import type { OrganizationInvitationStatus } from './organizationInvitation';
 import type { OrganizationMembershipResource } from './organizationMembership';
 import type { OrganizationSuggestionResource, OrganizationSuggestionStatus } from './organizationSuggestion';
+import type { ClerkPaginatedResponse, ClerkPaginationParams } from './pagination';
 import type { PhoneNumberResource } from './phoneNumber';
 import type { ClerkResource } from './resource';
 import type { SamlAccountResource } from './samlAccount';
@@ -148,42 +148,15 @@ export type UpdateUserPasswordParams = {
 
 export type RemoveUserPasswordParams = Pick<UpdateUserPasswordParams, 'currentPassword'>;
 
-export type GetUserOrganizationInvitationsParams = {
-  /**
-   * This the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
-
+export type GetUserOrganizationInvitationsParams = ClerkPaginationParams<{
   status?: OrganizationInvitationStatus;
-};
-
-export type GetUserOrganizationSuggestionsParams = {
-  /**
-   * This the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
+}>;
 
+export type GetUserOrganizationSuggestionsParams = ClerkPaginationParams<{
   status?: OrganizationSuggestionStatus | OrganizationSuggestionStatus[];
-};
+}>;
 
-export type GetUserOrganizationMembershipParams = {
-  /**
-   * This the starting point for your fetched results. The initial value persists between re-renders
-   */
-  initialPage?: number;
-  /**
-   * Maximum number of items returned per request. The initial value persists between re-renders
-   */
-  pageSize?: number;
-};
+export type GetUserOrganizationMembershipParams = ClerkPaginationParams;
 
 export type GetOrganizationMemberships = (
   params?: GetUserOrganizationMembershipParams,