feat: add total field to user search API response

The search API returns both users array and total count, but the SDK
was only returning the users array. This change updates the SDK to
return both fields in a UserSearchResponse object.

Changes:
- Added UserSearchResponse type with users and total fields
- Updated search() and searchTestUsers() to return UserSearchResponse
- Updated internal MultipleUsersResponse type to include total field
- Updated tests to verify total field is returned
- Kept deprecated searchAll() unchanged for backward compatibility

Fixes issue where SDK users couldn't access the total count returned
by the API, making pagination planning difficult.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: dorsha

lib/management/types.ts

@@ -582,6 +582,11 @@ export type PatchUserBatchResponse = {
   additionalErrors: Record<string, string>;
 };
 
+export type UserSearchResponse = {
+  users: UserResponse[];
+  total: number;
+};
+
 /**
  * Search options to filter which audit records we should retrieve.
  * All parameters are optional. `From` is currently limited to 30 days.

lib/management/user.test.ts

@@ -11,6 +11,7 @@ import {
   CreateOrInviteBatchResponse,
   PatchUserBatchResponse,
   UserPasswordHashed,
+  UserSearchResponse,
 } from './types';
 
 const management = withManagement(mockHttpClient);
@@ -25,6 +26,7 @@ const mockMgmtUserResponse = {
 
 const mockMgmtUsersResponse = {
   users: [mockUserResponse],
+  total: 1,
 };
 
 const mockMgmtInviteBatchResponse = {
@@ -1012,7 +1014,7 @@ describe('Management User', () => {
       };
       mockHttpClient.post.mockResolvedValue(httpResponse);
       const now = new Date().getTime();
-      const resp: SdkResponse<UserResponse[]> = await management.user.searchTestUsers({
+      const resp: SdkResponse<UserSearchResponse> = await management.user.searchTestUsers({
         tenantIds: ['t1'],
         roles: ['r1'],
         limit: 100,
@@ -1050,7 +1052,7 @@ describe('Management User', () => {
 
       expect(resp).toEqual({
         code: 200,
-        data: [mockUserResponse],
+        data: { users: [mockUserResponse], total: 1 },
         ok: true,
         response: httpResponse,
       });
@@ -1069,7 +1071,7 @@ describe('Management User', () => {
       };
       mockHttpClient.post.mockResolvedValue(httpResponse);
       const now = new Date().getTime();
-      const resp: SdkResponse<UserResponse[]> = await management.user.search({
+      const resp: SdkResponse<UserSearchResponse> = await management.user.search({
         tenantIds: ['t1'],
         roles: ['r1'],
         limit: 100,
@@ -1105,7 +1107,7 @@ describe('Management User', () => {
 
       expect(resp).toEqual({
         code: 200,
-        data: [mockUserResponse],
+        data: { users: [mockUserResponse], total: 1 },
         ok: true,
         response: httpResponse,
       });

lib/management/user.ts

@@ -21,6 +21,7 @@ import {
   TemplateOptions,
   ProviderTokenOptions,
   UserOptions,
+  UserSearchResponse,
 } from './types';
 import { DeliveryMethodForTestUser } from '../types';
 import apiPaths from './paths';
@@ -66,6 +67,7 @@ type SingleUserResponse = {
 
 type MultipleUsersResponse = {
   users: UserResponse[];
+  total: number;
 };
 
 const withUser = (httpClient: HttpClient) => {
@@ -618,25 +620,25 @@ const withUser = (httpClient: HttpClient) => {
         }),
         (data) => data.users,
       ),
-    searchTestUsers: (searchReq: SearchRequest): Promise<SdkResponse<UserResponse[]>> =>
-      transformResponse<MultipleUsersResponse, UserResponse[]>(
+    searchTestUsers: (searchReq: SearchRequest): Promise<SdkResponse<UserSearchResponse>> =>
+      transformResponse<MultipleUsersResponse, UserSearchResponse>(
         httpClient.post(apiPaths.user.searchTestUsers, {
           ...searchReq,
           withTestUser: true,
           testUsersOnly: true,
           roleNames: searchReq.roles,
           roles: undefined,
         }),
-        (data) => data.users,
+        (data) => ({ users: data.users, total: data.total }),
       ),
-    search: (searchReq: SearchRequest): Promise<SdkResponse<UserResponse[]>> =>
-      transformResponse<MultipleUsersResponse, UserResponse[]>(
+    search: (searchReq: SearchRequest): Promise<SdkResponse<UserSearchResponse>> =>
+      transformResponse<MultipleUsersResponse, UserSearchResponse>(
         httpClient.post(apiPaths.user.search, {
           ...searchReq,
           roleNames: searchReq.roles,
           roles: undefined,
         }),
-        (data) => data.users,
+        (data) => ({ users: data.users, total: data.total }),
       ),
     /**
      * Get the provider token for the given login ID.