fix(backend): Fix clerk.samlConnections.getSamlConnectionList return type (#6332)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 2 people

.changeset/young-steaks-chew.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Update `clerk.samlConnections.getSamlConnectionList()` to return paginated data and export the `SamlConnection` type.

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

@@ -12,33 +12,36 @@ describe('SamlConnectionAPI', () => {
 
   describe('getSamlConnectionList', () => {
     it('successfully fetches SAML connections with all parameters', async () => {
-      const mockSamlConnectionsResponse = [
-        {
-          object: 'saml_connection',
-          id: 'samlc_123',
-          name: 'Test Connection',
-          provider: 'saml_custom',
-          domain: 'test.example.com',
-          organization_id: 'org_123',
-          created_at: 1672531200000,
-          updated_at: 1672531200000,
-          active: true,
-          sync_user_attributes: false,
-          allow_subdomains: false,
-          allow_idp_initiated: false,
-          idp_entity_id: 'entity_123',
-          idp_sso_url: 'https://idp.example.com/sso',
-          idp_certificate: 'cert_data',
-          idp_metadata_url: null,
-          idp_metadata: null,
-          attribute_mapping: {
-            user_id: 'userId',
-            email_address: 'email',
-            first_name: 'firstName',
-            last_name: 'lastName',
+      const mockSamlConnectionsResponse = {
+        data: [
+          {
+            object: 'saml_connection',
+            id: 'samlc_123',
+            name: 'Test Connection',
+            provider: 'saml_custom',
+            domain: 'test.example.com',
+            organization_id: 'org_123',
+            created_at: 1672531200000,
+            updated_at: 1672531200000,
+            active: true,
+            sync_user_attributes: false,
+            allow_subdomains: false,
+            allow_idp_initiated: false,
+            idp_entity_id: 'entity_123',
+            idp_sso_url: 'https://idp.example.com/sso',
+            idp_certificate: 'cert_data',
+            idp_metadata_url: null,
+            idp_metadata: null,
+            attribute_mapping: {
+              user_id: 'userId',
+              email_address: 'email',
+              first_name: 'firstName',
+              last_name: 'lastName',
+            },
           },
-        },
-      ];
+        ],
+        total_count: 1,
+      };
 
       server.use(
         http.get(
@@ -50,7 +53,7 @@ describe('SamlConnectionAPI', () => {
             expect(url.searchParams.get('limit')).toBe('5');
             expect(url.searchParams.get('offset')).toBe('10');
             expect(url.searchParams.getAll('organization_id')).toEqual(['+org_123', '-org_456']);
-            return HttpResponse.json({ data: mockSamlConnectionsResponse });
+            return HttpResponse.json(mockSamlConnectionsResponse);
           }),
         ),
       );
@@ -63,10 +66,11 @@ describe('SamlConnectionAPI', () => {
         offset: 10,
       });
 
-      expect(response).toHaveLength(1);
-      expect(response[0].id).toBe('samlc_123');
-      expect(response[0].name).toBe('Test Connection');
-      expect(response[0].organizationId).toBe('org_123');
+      expect(response.data).toHaveLength(1);
+      expect(response.data[0].id).toBe('samlc_123');
+      expect(response.data[0].name).toBe('Test Connection');
+      expect(response.data[0].organizationId).toBe('org_123');
+      expect(response.totalCount).toBe(1);
     });
   });
 });

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

@@ -1,19 +1,32 @@
-import type { SamlIdpSlug } from '@clerk/types';
+import type { ClerkPaginationRequest, SamlIdpSlug } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
 import type { SamlConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 import type { WithSign } from './util-types';
 
 const basePath = '/saml_connections';
 
-type SamlConnectionListParams = {
-  limit?: number;
-  offset?: number;
+type SamlConnectionListParams = ClerkPaginationRequest<{
+  /**
+   * Returns SAML connections that have a name that matches the given query, via case-insensitive partial match.
+   */
   query?: string;
+
+  /**
+   * Sorts SAML connections by phone_number, email_address, created_at, first_name, last_name or username.
+   * By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.
+   */
   orderBy?: WithSign<'phone_number' | 'email_address' | 'created_at' | 'first_name' | 'last_name' | 'username'>;
+
+  /**
+   * Returns SAML connections that have an associated organization ID to the given organizations.
+   * For each organization id, the + and - can be prepended to the id, which denote whether the
+   * respective organization should be included or excluded from the result set. Accepts up to 100 organization ids.
+   */
   organizationId?: WithSign<string>[];
-};
+}>;
 
 type CreateSamlConnectionParams = {
   name: string;
@@ -57,7 +70,7 @@ type UpdateSamlConnectionParams = {
 
 export class SamlConnectionAPI extends AbstractAPI {
   public async getSamlConnectionList(params: SamlConnectionListParams = {}) {
-    return this.request<SamlConnection[]>({
+    return this.request<PaginatedResourceResponse<SamlConnection[]>>({
       method: 'GET',
       path: basePath,
       queryParams: params,

packages/backend/src/index.ts

@@ -131,6 +131,7 @@ export type {
   OrganizationMembershipPublicUserData,
   OrganizationSettings,
   PhoneNumber,
+  SamlConnection,
   Session,
   SignInToken,
   SignUpAttempt,