From b4dd686a778cc111b4ceecd9edbdfe7375f85a12 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 18 Nov 2025 19:14:22 +0000
Subject: [PATCH 01/15] feat: Implement support for accounts:query

Adds the `QueryUsers` function to the Auth client, allowing users to query for user accounts with various filters.

- Defines `QueryUsersRequest` and `QueryUsersResponse` structs.
- Implements the `QueryUsers` function to call the `accounts:query` endpoint.
- Includes support for tenant-specific queries.
- Adds comprehensive unit tests for the new functionality.
---
 auth/user_mgt.go      |  82 ++++++++++++++++++++++++++
 auth/user_mgt_test.go | 134 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 216 insertions(+)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index bee027e3..b64b5de6 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -838,6 +838,61 @@ type getAccountInfoResponse struct {
 	Users []*userQueryResponse `json:"users"`
 }
 
+// QueryUserInfoResponse is the response structure for the accounts:query endpoint.
+type QueryUserInfoResponse struct {
+	Users []*UserRecord
+	Count string
+}
+
+type queryUsersResponse struct {
+	Users []*userQueryResponse `json:"usersInfo,omitempty"`
+	Count string               `json:"recordsCount,omitempty"`
+}
+
+// SqlExpression is a query condition used to filter results.
+type SqlExpression struct {
+	Email       string `json:"email,omitempty"`
+	UserID      string `json:"userId,omitempty"`
+	PhoneNumber string `json:"phoneNumber,omitempty"`
+}
+
+// QueryUsersRequest is the request structure for the accounts:query endpoint.
+type QueryUsersRequest struct {
+	ReturnUserInfo bool             `json:"returnUserInfo"`
+	Limit          string           `json:"limit,omitempty"`
+	Offset         string           `json:"offset,omitempty"`
+	SortBy         string           `json:"sortBy,omitempty"`
+	Order          string           `json:"order,omitempty"`
+	TenantID       string           `json:"tenantId,omitempty"`
+	Expression     []*SqlExpression `json:"expression,omitempty"`
+}
+
+// SortByField is a field to use for sorting user accounts.
+type SortByField string
+
+const (
+	// UserID sorts results by userId.
+	UserID SortByField = "USER_ID"
+	// Name sorts results by name.
+	Name SortByField = "NAME"
+	// CreatedAt sorts results by createdAt.
+	CreatedAt SortByField = "CREATED_AT"
+	// LastLoginAt sorts results by lastLoginAt.
+	LastLoginAt SortByField = "LAST_LOGIN_AT"
+	// UserEmail sorts results by userEmail.
+	UserEmail SortByField = "USER_EMAIL"
+)
+
+// Order is an order for sorting query results.
+type Order string
+
+const (
+	// Asc sorts in ascending order.
+	Asc Order = "ASC"
+	// Desc sorts in descending order.
+	Desc Order = "DESC"
+)
+
 func (c *baseClient) getUser(ctx context.Context, query *userQuery) (*UserRecord, error) {
 	var parsed getAccountInfoResponse
 	resp, err := c.post(ctx, "/accounts:lookup", query.build(), &parsed)
@@ -1311,6 +1366,33 @@ type DeleteUsersErrorInfo struct {
 // array of errors that correspond to the failed deletions. An error is
 // returned if any of the identifiers are invalid or if more than 1000
 // identifiers are specified.
+// QueryUsers queries for user accounts based on the provided query configuration.
+func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (*QueryUserInfoResponse, error) {
+	if query == nil {
+		return nil, fmt.Errorf("query request must not be nil")
+	}
+
+	var parsed queryUsersResponse
+	_, err := c.post(ctx, "/accounts:query", query, &parsed)
+	if err != nil {
+		return nil, err
+	}
+
+	var userRecords []*UserRecord
+	for _, user := range parsed.Users {
+		userRecord, err := user.makeUserRecord()
+		if err != nil {
+			return nil, fmt.Errorf("error while parsing response: %w", err)
+		}
+		userRecords = append(userRecords, userRecord)
+	}
+
+	return &QueryUserInfoResponse{
+		Users: userRecords,
+		Count: parsed.Count,
+	}, nil
+}
+
 func (c *baseClient) DeleteUsers(ctx context.Context, uids []string) (*DeleteUsersResult, error) {
 	if len(uids) == 0 {
 		return &DeleteUsersResult{}, nil
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 01d8734f..e43d4249 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -1899,6 +1899,140 @@ func TestDeleteUsers(t *testing.T) {
 	})
 }
 
+func TestQueryUsers(t *testing.T) {
+	resp := `{
+		"usersInfo": [{
+			"localId": "testuser",
+			"email": "testuser@example.com",
+			"phoneNumber": "+1234567890",
+			"emailVerified": true,
+			"displayName": "Test User",
+			"photoUrl": "http://www.example.com/testuser/photo.png",
+			"validSince": "1494364393",
+			"disabled": false,
+			"createdAt": "1234567890000",
+			"lastLoginAt": "1233211232000",
+			"customAttributes": "{\"admin\": true, \"package\": \"gold\"}",
+			"tenantId": "testTenant",
+			"providerUserInfo": [{
+				"providerId": "password",
+				"displayName": "Test User",
+				"photoUrl": "http://www.example.com/testuser/photo.png",
+				"email": "testuser@example.com",
+				"rawId": "testuid"
+			}, {
+				"providerId": "phone",
+				"phoneNumber": "+1234567890",
+				"rawId": "testuid"
+			}],
+			"mfaInfo": [{
+				"phoneInfo": "+1234567890",
+				"mfaEnrollmentId": "enrolledPhoneFactor",
+				"displayName": "My MFA Phone",
+				"enrolledAt": "2021-03-03T13:06:20.542896Z"
+			}, {
+				"totpInfo": {},
+				"mfaEnrollmentId": "enrolledTOTPFactor",
+				"displayName": "My MFA TOTP",
+				"enrolledAt": "2021-03-03T13:06:20.542896Z"
+			}]
+		}],
+		"recordsCount": "1"
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+
+	query := &QueryUsersRequest{
+		ReturnUserInfo: true,
+		Limit:          "1",
+		SortBy:         string(UserEmail),
+		Order:          string(Asc),
+		Expression: []*SqlExpression{
+			{
+				Email: "testuser@example.com",
+			},
+		},
+	}
+
+	result, err := s.Client.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() = %v", err)
+	}
+
+	if len(result.Users) != 1 {
+		t.Fatalf("QueryUsers() returned %d users; want 1", len(result.Users))
+	}
+
+	if result.Count != "1" {
+		t.Errorf("QueryUsers() returned count %q; want '1'", result.Count)
+	}
+
+	if !reflect.DeepEqual(result.Users[0], testUser) {
+		t.Errorf("QueryUsers() = %#v; want = %#v", result.Users[0], testUser)
+	}
+
+	wantPath := "/projects/mock-project-id/accounts:query"
+	if s.Req[0].RequestURI != wantPath {
+		t.Errorf("QueryUsers() URL = %q; want = %q", s.Req[0].RequestURI, wantPath)
+	}
+}
+
+func TestQueryUsersError(t *testing.T) {
+	resp := `{
+		"error": {
+			"message": "INVALID_QUERY"
+		}
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+	s.Status = http.StatusBadRequest
+
+	query := &QueryUsersRequest{
+		ReturnUserInfo: true,
+		Limit:          "1",
+		SortBy:         "USER_EMAIL",
+		Order:          "ASC",
+		Expression: []*SqlExpression{
+			{
+				Email: "testuser@example.com",
+			},
+		},
+	}
+
+	result, err := s.Client.QueryUsers(context.Background(), query)
+	if result != nil || err == nil {
+		t.Fatalf("QueryUsers() = (%v, %v); want = (nil, error)", result, err)
+	}
+}
+
+func TestQueryUsersWithTenant(t *testing.T) {
+	resp := `{
+		"usersInfo": [],
+		"recordsCount": "0"
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+
+	query := &QueryUsersRequest{
+		ReturnUserInfo: true,
+		TenantID:       "test-tenant",
+	}
+
+	_, err := s.Client.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() = %v", err)
+	}
+
+	var req map[string]interface{}
+	if err := json.Unmarshal(s.Rbody, &req); err != nil {
+		t.Fatal(err)
+	}
+
+	if req["tenantId"] != "test-tenant" {
+		t.Errorf("QueryUsers() tenantId = %q; want = %q", req["tenantId"], "test-tenant")
+	}
+}
+
 func TestMakeExportedUser(t *testing.T) {
 	queryResponse := &userQueryResponse{
 		UID:                "testuser",

From 68185fa94e3bc76f784b8858c44cf7cbb76375a5 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 18 Nov 2025 19:22:35 +0000
Subject: [PATCH 02/15] fix: Correct tenant query test and request struct

- Updates the `TestQueryUsersWithTenant` to create a tenant-specific client and verify the request URL.
- Corrects the `QueryUsersRequest` struct to use `string` for `Limit` and `Offset` fields, and adds the `TenantID` field.
- Updates the test cases to reflect the struct changes.
---
 auth/user_mgt_test.go | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index e43d4249..1b3b818c 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -2013,23 +2013,23 @@ func TestQueryUsersWithTenant(t *testing.T) {
 	s := echoServer([]byte(resp), t)
 	defer s.Close()
 
+	tenantClient, err := s.Client.TenantManager.AuthForTenant("test-tenant")
+	if err != nil {
+		t.Fatalf("Failed to create tenant client: %v", err)
+	}
+
 	query := &QueryUsersRequest{
 		ReturnUserInfo: true,
-		TenantID:       "test-tenant",
 	}
 
-	_, err := s.Client.QueryUsers(context.Background(), query)
+	_, err = tenantClient.QueryUsers(context.Background(), query)
 	if err != nil {
-		t.Fatalf("QueryUsers() = %v", err)
-	}
-
-	var req map[string]interface{}
-	if err := json.Unmarshal(s.Rbody, &req); err != nil {
-		t.Fatal(err)
+		t.Fatalf("QueryUsers() with tenant client = %v", err)
 	}
 
-	if req["tenantId"] != "test-tenant" {
-		t.Errorf("QueryUsers() tenantId = %q; want = %q", req["tenantId"], "test-tenant")
+	wantPath := "/projects/mock-project-id/tenants/test-tenant/accounts:query"
+	if s.Req[0].RequestURI != wantPath {
+		t.Errorf("QueryUsers() URL = %q; want = %q", s.Req[0].RequestURI, wantPath)
 	}
 }
 

From 0f2f27475b3c0ad1d788f909169a8f90696b6c84 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 18 Nov 2025 19:30:21 +0000
Subject: [PATCH 03/15] refactor: Move tenant query test to tenant_mgt_test.go

Moves the tenant-specific test for `QueryUsers` to `tenant_mgt_test.go` to follow the existing test structure.

- Renames `TestQueryUsersWithTenant` to `TestTenantQueryUsers`.
- Moves the test function to `auth/tenant_mgt_test.go`.
---
 auth/tenant_mgt_test.go | 28 ++++++++++++++++++++++++++++
 auth/user_mgt_test.go   | 28 ----------------------------
 2 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/auth/tenant_mgt_test.go b/auth/tenant_mgt_test.go
index e411793c..bc7d814b 100644
--- a/auth/tenant_mgt_test.go
+++ b/auth/tenant_mgt_test.go
@@ -90,6 +90,34 @@ func TestTenantGetUser(t *testing.T) {
 	}
 }
 
+func TestTenantQueryUsers(t *testing.T) {
+	resp := `{
+		"usersInfo": [],
+		"recordsCount": "0"
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+
+	tenantClient, err := s.Client.TenantManager.AuthForTenant("test-tenant")
+	if err != nil {
+		t.Fatalf("Failed to create tenant client: %v", err)
+	}
+
+	query := &QueryUsersRequest{
+		ReturnUserInfo: true,
+	}
+
+	_, err = tenantClient.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() with tenant client = %v", err)
+	}
+
+	wantPath := "/projects/mock-project-id/tenants/test-tenant/accounts:query"
+	if s.Req[0].RequestURI != wantPath {
+		t.Errorf("QueryUsers() URL = %q; want = %q", s.Req[0].RequestURI, wantPath)
+	}
+}
+
 func TestTenantGetUserByEmail(t *testing.T) {
 	s := echoServer(testGetUserResponse, t)
 	defer s.Close()
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 1b3b818c..6b51727d 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -2005,34 +2005,6 @@ func TestQueryUsersError(t *testing.T) {
 	}
 }
 
-func TestQueryUsersWithTenant(t *testing.T) {
-	resp := `{
-		"usersInfo": [],
-		"recordsCount": "0"
-	}`
-	s := echoServer([]byte(resp), t)
-	defer s.Close()
-
-	tenantClient, err := s.Client.TenantManager.AuthForTenant("test-tenant")
-	if err != nil {
-		t.Fatalf("Failed to create tenant client: %v", err)
-	}
-
-	query := &QueryUsersRequest{
-		ReturnUserInfo: true,
-	}
-
-	_, err = tenantClient.QueryUsers(context.Background(), query)
-	if err != nil {
-		t.Fatalf("QueryUsers() with tenant client = %v", err)
-	}
-
-	wantPath := "/projects/mock-project-id/tenants/test-tenant/accounts:query"
-	if s.Req[0].RequestURI != wantPath {
-		t.Errorf("QueryUsers() URL = %q; want = %q", s.Req[0].RequestURI, wantPath)
-	}
-}
-
 func TestMakeExportedUser(t *testing.T) {
 	queryResponse := &userQueryResponse{
 		UID:                "testuser",

From d14f9b7775b47293c203b511bc19cc1057509294 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 18 Nov 2025 19:57:08 +0000
Subject: [PATCH 04/15] style: Rename SqlExpression to SQLExpression

Renames the `SqlExpression` struct to `SQLExpression` to conform to Go's linting standards for acronyms.

- Updates the struct definition in `auth/user_mgt.go`.
- Updates all usages of the struct in `auth/user_mgt.go` and `auth/user_mgt_test.go`.
---
 auth/user_mgt.go      | 6 +++---
 auth/user_mgt_test.go | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index b64b5de6..e40602d3 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -849,8 +849,8 @@ type queryUsersResponse struct {
 	Count string               `json:"recordsCount,omitempty"`
 }
 
-// SqlExpression is a query condition used to filter results.
-type SqlExpression struct {
+// SQLExpression is a query condition used to filter results.
+type SQLExpression struct {
 	Email       string `json:"email,omitempty"`
 	UserID      string `json:"userId,omitempty"`
 	PhoneNumber string `json:"phoneNumber,omitempty"`
@@ -864,7 +864,7 @@ type QueryUsersRequest struct {
 	SortBy         string           `json:"sortBy,omitempty"`
 	Order          string           `json:"order,omitempty"`
 	TenantID       string           `json:"tenantId,omitempty"`
-	Expression     []*SqlExpression `json:"expression,omitempty"`
+	Expression     []*SQLExpression `json:"expression,omitempty"`
 }
 
 // SortByField is a field to use for sorting user accounts.
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 6b51727d..73ccd091 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -1947,7 +1947,7 @@ func TestQueryUsers(t *testing.T) {
 		Limit:          "1",
 		SortBy:         string(UserEmail),
 		Order:          string(Asc),
-		Expression: []*SqlExpression{
+		Expression: []*SQLExpression{
 			{
 				Email: "testuser@example.com",
 			},
@@ -1992,7 +1992,7 @@ func TestQueryUsersError(t *testing.T) {
 		Limit:          "1",
 		SortBy:         "USER_EMAIL",
 		Order:          "ASC",
-		Expression: []*SqlExpression{
+		Expression: []*SQLExpression{
 			{
 				Email: "testuser@example.com",
 			},

From 52d6257c016a8474e9a5c694ffdb2c6c8a473174 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Fri, 21 Nov 2025 20:17:01 +0000
Subject: [PATCH 05/15] json marshalling fixes

---
 auth/user_mgt.go        | 14 +++++++++-----
 internal/http_client.go |  2 ++
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index e40602d3..54593313 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -841,12 +841,12 @@ type getAccountInfoResponse struct {
 // QueryUserInfoResponse is the response structure for the accounts:query endpoint.
 type QueryUserInfoResponse struct {
 	Users []*UserRecord
-	Count string
+	Count int64
 }
 
 type queryUsersResponse struct {
-	Users []*userQueryResponse `json:"usersInfo,omitempty"`
-	Count string               `json:"recordsCount,omitempty"`
+	Users []*userQueryResponse `json:"userInfo"`
+	Count int64                `json:"recordsCount,string,omitempty"`
 }
 
 // SQLExpression is a query condition used to filter results.
@@ -859,8 +859,8 @@ type SQLExpression struct {
 // QueryUsersRequest is the request structure for the accounts:query endpoint.
 type QueryUsersRequest struct {
 	ReturnUserInfo bool             `json:"returnUserInfo"`
-	Limit          string           `json:"limit,omitempty"`
-	Offset         string           `json:"offset,omitempty"`
+	Limit          int64            `json:"limit,string,omitempty"`
+	Offset         int64            `json:"offset,string,omitempty"`
 	SortBy         string           `json:"sortBy,omitempty"`
 	Order          string           `json:"order,omitempty"`
 	TenantID       string           `json:"tenantId,omitempty"`
@@ -1378,6 +1378,8 @@ func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (
 		return nil, err
 	}
 
+	//log.Printf("QueryUsers() with response = %d, %d", parsed.Count, len(parsed.Users))
+
 	var userRecords []*UserRecord
 	for _, user := range parsed.Users {
 		userRecord, err := user.makeUserRecord()
@@ -1480,6 +1482,8 @@ func (c *baseClient) post(
 		URL:    url,
 		Body:   internal.NewJSONEntity(payload),
 	}
+	//log.Printf("%+v \n", req.Body)
+	//log.Printf("%+v \n", resp)
 	return c.httpClient.DoAndUnmarshal(ctx, req, resp)
 }
 
diff --git a/internal/http_client.go b/internal/http_client.go
index 9d1257bc..d29af2f5 100644
--- a/internal/http_client.go
+++ b/internal/http_client.go
@@ -167,6 +167,8 @@ func (c *HTTPClient) DoAndUnmarshal(ctx context.Context, req *Request, v interfa
 		return nil, err
 	}
 
+	//log.Printf("%+v \n", string(resp.Body))
+
 	if v != nil {
 		if err := json.Unmarshal(resp.Body, v); err != nil {
 			return nil, fmt.Errorf("error while parsing response: %v", err)

From 3d21021d20e9b2d2f1bec82d4e5042a907ada2f4 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Mon, 24 Nov 2025 23:08:51 +0000
Subject: [PATCH 06/15] code cleanup

---
 auth/user_mgt.go      | 207 +++++++++++++++++++++++++-----------------
 auth/user_mgt_test.go |  59 ++++++++++--
 2 files changed, 173 insertions(+), 93 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index 54593313..259e3c57 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -838,61 +838,6 @@ type getAccountInfoResponse struct {
 	Users []*userQueryResponse `json:"users"`
 }
 
-// QueryUserInfoResponse is the response structure for the accounts:query endpoint.
-type QueryUserInfoResponse struct {
-	Users []*UserRecord
-	Count int64
-}
-
-type queryUsersResponse struct {
-	Users []*userQueryResponse `json:"userInfo"`
-	Count int64                `json:"recordsCount,string,omitempty"`
-}
-
-// SQLExpression is a query condition used to filter results.
-type SQLExpression struct {
-	Email       string `json:"email,omitempty"`
-	UserID      string `json:"userId,omitempty"`
-	PhoneNumber string `json:"phoneNumber,omitempty"`
-}
-
-// QueryUsersRequest is the request structure for the accounts:query endpoint.
-type QueryUsersRequest struct {
-	ReturnUserInfo bool             `json:"returnUserInfo"`
-	Limit          int64            `json:"limit,string,omitempty"`
-	Offset         int64            `json:"offset,string,omitempty"`
-	SortBy         string           `json:"sortBy,omitempty"`
-	Order          string           `json:"order,omitempty"`
-	TenantID       string           `json:"tenantId,omitempty"`
-	Expression     []*SQLExpression `json:"expression,omitempty"`
-}
-
-// SortByField is a field to use for sorting user accounts.
-type SortByField string
-
-const (
-	// UserID sorts results by userId.
-	UserID SortByField = "USER_ID"
-	// Name sorts results by name.
-	Name SortByField = "NAME"
-	// CreatedAt sorts results by createdAt.
-	CreatedAt SortByField = "CREATED_AT"
-	// LastLoginAt sorts results by lastLoginAt.
-	LastLoginAt SortByField = "LAST_LOGIN_AT"
-	// UserEmail sorts results by userEmail.
-	UserEmail SortByField = "USER_EMAIL"
-)
-
-// Order is an order for sorting query results.
-type Order string
-
-const (
-	// Asc sorts in ascending order.
-	Asc Order = "ASC"
-	// Desc sorts in descending order.
-	Desc Order = "DESC"
-)
-
 func (c *baseClient) getUser(ctx context.Context, query *userQuery) (*UserRecord, error) {
 	var parsed getAccountInfoResponse
 	resp, err := c.post(ctx, "/accounts:lookup", query.build(), &parsed)
@@ -1103,6 +1048,129 @@ func (c *baseClient) GetUsers(
 	return &GetUsersResult{userRecords, notFound}, nil
 }
 
+// QueryUserInfoResponse is the response structure for the accounts:query endpoint.
+type QueryUserInfoResponse struct {
+	Users []*UserRecord
+	Count int64
+}
+
+type queryUsersResponse struct {
+	Users []*userQueryResponse `json:"userInfo"`
+	Count int64                `json:"recordsCount,string,omitempty"`
+}
+
+// SQLExpression is a query condition used to filter results.
+type SQLExpression struct {
+	Email       string `json:"email,omitempty"`
+	UID      string `json:"userId,omitempty"`
+	PhoneNumber string `json:"phoneNumber,omitempty"`
+}
+
+// QueryUsersRequest is the request structure for the accounts:query endpoint.
+type QueryUsersRequest struct {
+	ReturnUserInfo bool             `json:"returnUserInfo"`
+	Limit          int64            `json:"limit,string,omitempty"`
+	Offset         int64            `json:"offset,string,omitempty"`
+	SortBy         SortByField      `json:"-"`
+	Order          Order            `json:"-"`
+	TenantID       string           `json:"tenantId,omitempty"`
+	Expression     []*SQLExpression `json:"expression,omitempty"`
+}
+
+// MarshalJSON marshals a QueryUsersRequest into JSON (for internal use only).
+func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
+	var sortBy string
+	if q.SortBy != sortByUnspecified {
+		sortBys := map[SortByField]string{
+			UID:      "USER_ID",
+			Name:        "NAME",
+			CreatedAt:   "CREATED_AT",
+			LastLoginAt: "LAST_LOGIN_AT",
+			UserEmail:   "USER_EMAIL",
+		}
+		sortBy = sortBys[q.SortBy]
+	}
+
+	var order string
+	if q.Order != orderUnspecified {
+		orders := map[Order]string{
+			Asc:  "ASC",
+			Desc: "DESC",
+		}
+		order = orders[q.Order]
+	}
+
+	type queryUsersRequestInternal QueryUsersRequest
+	temp := &struct {
+		SortBy string `json:"sortBy,omitempty"`
+		Order  string `json:"order,omitempty"`
+		*queryUsersRequestInternal
+	}{
+		SortBy:                    sortBy,
+		Order:                     order,
+		queryUsersRequestInternal: (*queryUsersRequestInternal)(q),
+	}
+	return json.Marshal(temp)
+}
+
+// SortByField is a field to use for sorting user accounts.
+type SortByField int
+
+const (
+	sortByUnspecified SortByField = iota
+	// UID sorts results by userId.
+	UID
+	// Name sorts results by name.
+	Name
+	// CreatedAt sorts results by createdAt.
+	CreatedAt
+	// LastLoginAt sorts results by lastLoginAt.
+	LastLoginAt
+	// UserEmail sorts results by userEmail.
+	UserEmail
+)
+
+// Order is an order for sorting query results.
+type Order int
+
+const (
+	orderUnspecified Order = iota
+	// Asc sorts in ascending order.
+	Asc
+	// Desc sorts in descending order.
+	Desc
+)
+
+// QueryUsers queries for user accounts based on the provided query configuration.
+func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (*QueryUserInfoResponse, error) {
+	if query == nil {
+		return nil, fmt.Errorf("query request must not be nil")
+	}
+
+	var parsed queryUsersResponse
+	_, err := c.post(ctx, "/accounts:query", query, &parsed)
+	if err != nil {
+		return nil, err
+	}
+
+	//log.Printf("QueryUsers() with response = %d, %d", parsed.Count, len(parsed.Users))
+
+	var userRecords []*UserRecord
+	for _, user := range parsed.Users {
+		userRecord, err := user.makeUserRecord()
+		if err != nil {
+			return nil, fmt.Errorf("error while parsing response: %w", err)
+		}
+		userRecords = append(userRecords, userRecord)
+	}
+
+	return &QueryUserInfoResponse{
+		Users: userRecords,
+		Count: parsed.Count,
+	}, nil
+}
+
+
 type userQueryResponse struct {
 	UID                string                     `json:"localId,omitempty"`
 	DisplayName        string                     `json:"displayName,omitempty"`
@@ -1366,35 +1434,6 @@ type DeleteUsersErrorInfo struct {
 // array of errors that correspond to the failed deletions. An error is
 // returned if any of the identifiers are invalid or if more than 1000
 // identifiers are specified.
-// QueryUsers queries for user accounts based on the provided query configuration.
-func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (*QueryUserInfoResponse, error) {
-	if query == nil {
-		return nil, fmt.Errorf("query request must not be nil")
-	}
-
-	var parsed queryUsersResponse
-	_, err := c.post(ctx, "/accounts:query", query, &parsed)
-	if err != nil {
-		return nil, err
-	}
-
-	//log.Printf("QueryUsers() with response = %d, %d", parsed.Count, len(parsed.Users))
-
-	var userRecords []*UserRecord
-	for _, user := range parsed.Users {
-		userRecord, err := user.makeUserRecord()
-		if err != nil {
-			return nil, fmt.Errorf("error while parsing response: %w", err)
-		}
-		userRecords = append(userRecords, userRecord)
-	}
-
-	return &QueryUserInfoResponse{
-		Users: userRecords,
-		Count: parsed.Count,
-	}, nil
-}
-
 func (c *baseClient) DeleteUsers(ctx context.Context, uids []string) (*DeleteUsersResult, error) {
 	if len(uids) == 0 {
 		return &DeleteUsersResult{}, nil
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 73ccd091..a862bfe2 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -1901,7 +1901,7 @@ func TestDeleteUsers(t *testing.T) {
 
 func TestQueryUsers(t *testing.T) {
 	resp := `{
-		"usersInfo": [{
+		"userInfo": [{
 			"localId": "testuser",
 			"email": "testuser@example.com",
 			"phoneNumber": "+1234567890",
@@ -1944,9 +1944,9 @@ func TestQueryUsers(t *testing.T) {
 
 	query := &QueryUsersRequest{
 		ReturnUserInfo: true,
-		Limit:          "1",
-		SortBy:         string(UserEmail),
-		Order:          string(Asc),
+		Limit:          1,
+		SortBy:         UserEmail,
+		Order:          Asc,
 		Expression: []*SQLExpression{
 			{
 				Email: "testuser@example.com",
@@ -1963,8 +1963,8 @@ func TestQueryUsers(t *testing.T) {
 		t.Fatalf("QueryUsers() returned %d users; want 1", len(result.Users))
 	}
 
-	if result.Count != "1" {
-		t.Errorf("QueryUsers() returned count %q; want '1'", result.Count)
+	if result.Count != 1 {
+		t.Errorf("QueryUsers() returned count %d; want 1", result.Count)
 	}
 
 	if !reflect.DeepEqual(result.Users[0], testUser) {
@@ -1989,9 +1989,9 @@ func TestQueryUsersError(t *testing.T) {
 
 	query := &QueryUsersRequest{
 		ReturnUserInfo: true,
-		Limit:          "1",
-		SortBy:         "USER_EMAIL",
-		Order:          "ASC",
+		Limit:          1,
+		SortBy:         UserEmail,
+		Order:          Asc,
 		Expression: []*SQLExpression{
 			{
 				Email: "testuser@example.com",
@@ -2005,6 +2005,47 @@ func TestQueryUsersError(t *testing.T) {
 	}
 }
 
+func TestQueryUsersNilQuery(t *testing.T) {
+	s := echoServer([]byte("{}"), t)
+	defer s.Close()
+	result, err := s.Client.QueryUsers(context.Background(), nil)
+	if result != nil || err == nil {
+		t.Fatalf("QueryUsers(nil) = (%v, %v); want = (nil, error)", result, err)
+	}
+}
+
+func TestQueryUsersMalformedCustomAttributes(t *testing.T) {
+	resp := `{
+		"userInfo": [{
+			"localId": "testuser",
+			"customAttributes": "invalid-json"
+		}]
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+	query := &QueryUsersRequest{}
+	result, err := s.Client.QueryUsers(context.Background(), query)
+	if result != nil || err == nil {
+		t.Fatalf("QueryUsers() = (%v, %v); want = (nil, error)", result, err)
+	}
+}
+
+func TestQueryUsersMalformedLastRefreshTimestamp(t *testing.T) {
+	resp := `{
+		"userInfo": [{
+			"localId": "testuser",
+			"lastRefreshAt": "invalid-timestamp"
+		}]
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+	query := &QueryUsersRequest{}
+	result, err := s.Client.QueryUsers(context.Background(), query)
+	if result != nil || err == nil {
+		t.Fatalf("QueryUsers() = (%v, %v); want = (nil, error)", result, err)
+	}
+}
+
 func TestMakeExportedUser(t *testing.T) {
 	queryResponse := &userQueryResponse{
 		UID:                "testuser",

From 4b6812dbbce1e6438a03f58553ae9ec847fbbac5 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Mon, 24 Nov 2025 23:13:23 +0000
Subject: [PATCH 07/15] Fix linting issues and format auth/user_mgt.go

---
 auth/user_mgt.go | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index 259e3c57..4f627288 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1062,7 +1062,7 @@ type queryUsersResponse struct {
 // SQLExpression is a query condition used to filter results.
 type SQLExpression struct {
 	Email       string `json:"email,omitempty"`
-	UID      string `json:"userId,omitempty"`
+	UID         string `json:"userId,omitempty"`
 	PhoneNumber string `json:"phoneNumber,omitempty"`
 }
 
@@ -1082,7 +1082,7 @@ func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
 	var sortBy string
 	if q.SortBy != sortByUnspecified {
 		sortBys := map[SortByField]string{
-			UID:      "USER_ID",
+			UID:         "USER_ID",
 			Name:        "NAME",
 			CreatedAt:   "CREATED_AT",
 			LastLoginAt: "LAST_LOGIN_AT",
@@ -1170,7 +1170,6 @@ func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (
 	}, nil
 }
 
-
 type userQueryResponse struct {
 	UID                string                     `json:"localId,omitempty"`
 	DisplayName        string                     `json:"displayName,omitempty"`

From 0e145b0ed60cf0637c72b7e604b86173e8d6e8f1 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Tue, 25 Nov 2025 19:44:01 +0000
Subject: [PATCH 08/15] update sort by enum type

---
 auth/user_mgt.go | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index 4f627288..f406ec82 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1071,7 +1071,7 @@ type QueryUsersRequest struct {
 	ReturnUserInfo bool             `json:"returnUserInfo"`
 	Limit          int64            `json:"limit,string,omitempty"`
 	Offset         int64            `json:"offset,string,omitempty"`
-	SortBy         SortByField      `json:"-"`
+	SortBy         SortBy           `json:"-"`
 	Order          Order            `json:"-"`
 	TenantID       string           `json:"tenantId,omitempty"`
 	Expression     []*SQLExpression `json:"expression,omitempty"`
@@ -1081,7 +1081,7 @@ type QueryUsersRequest struct {
 func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
 	var sortBy string
 	if q.SortBy != sortByUnspecified {
-		sortBys := map[SortByField]string{
+		sortBys := map[SortBy]string{
 			UID:         "USER_ID",
 			Name:        "NAME",
 			CreatedAt:   "CREATED_AT",
@@ -1113,11 +1113,11 @@ func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
 	return json.Marshal(temp)
 }
 
-// SortByField is a field to use for sorting user accounts.
-type SortByField int
+// SortBy is a field to use for sorting user accounts.
+type SortBy int
 
 const (
-	sortByUnspecified SortByField = iota
+	sortByUnspecified SortBy = iota
 	// UID sorts results by userId.
 	UID
 	// Name sorts results by name.

From 784ca1b983e96edd56bd1ae0d9a3c68a363d47a5 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Tue, 25 Nov 2025 20:03:43 +0000
Subject: [PATCH 09/15] rename Expression

---
 auth/user_mgt.go      | 18 +++++++++---------
 auth/user_mgt_test.go |  4 ++--
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index f406ec82..ff738a27 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1059,8 +1059,8 @@ type queryUsersResponse struct {
 	Count int64                `json:"recordsCount,string,omitempty"`
 }
 
-// SQLExpression is a query condition used to filter results.
-type SQLExpression struct {
+// Expression is a query condition used to filter results.
+type Expression struct {
 	Email       string `json:"email,omitempty"`
 	UID         string `json:"userId,omitempty"`
 	PhoneNumber string `json:"phoneNumber,omitempty"`
@@ -1068,13 +1068,13 @@ type SQLExpression struct {
 
 // QueryUsersRequest is the request structure for the accounts:query endpoint.
 type QueryUsersRequest struct {
-	ReturnUserInfo bool             `json:"returnUserInfo"`
-	Limit          int64            `json:"limit,string,omitempty"`
-	Offset         int64            `json:"offset,string,omitempty"`
-	SortBy         SortBy           `json:"-"`
-	Order          Order            `json:"-"`
-	TenantID       string           `json:"tenantId,omitempty"`
-	Expression     []*SQLExpression `json:"expression,omitempty"`
+	ReturnUserInfo bool          `json:"returnUserInfo"`
+	Limit          int64         `json:"limit,string,omitempty"`
+	Offset         int64         `json:"offset,string,omitempty"`
+	SortBy         SortBy        `json:"-"`
+	Order          Order         `json:"-"`
+	TenantID       string        `json:"tenantId,omitempty"`
+	Expression     []*Expression `json:"expression,omitempty"`
 }
 
 // MarshalJSON marshals a QueryUsersRequest into JSON (for internal use only).
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index a862bfe2..918a2a4f 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -1947,7 +1947,7 @@ func TestQueryUsers(t *testing.T) {
 		Limit:          1,
 		SortBy:         UserEmail,
 		Order:          Asc,
-		Expression: []*SQLExpression{
+		Expression: []*Expression{
 			{
 				Email: "testuser@example.com",
 			},
@@ -1992,7 +1992,7 @@ func TestQueryUsersError(t *testing.T) {
 		Limit:          1,
 		SortBy:         UserEmail,
 		Order:          Asc,
-		Expression: []*SQLExpression{
+		Expression: []*Expression{
 			{
 				Email: "testuser@example.com",
 			},

From a2241eab44e53f515f97a894ebbe2da0f7f95a94 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Tue, 25 Nov 2025 20:18:25 +0000
Subject: [PATCH 10/15] Clean up JSON marshalling and query building

---
 auth/user_mgt.go | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index ff738a27..767b6bf9 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1077,8 +1077,8 @@ type QueryUsersRequest struct {
 	Expression     []*Expression `json:"expression,omitempty"`
 }
 
-// MarshalJSON marshals a QueryUsersRequest into JSON (for internal use only).
-func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
+// build builds the query request (for internal use only).
+func (q *QueryUsersRequest) build() interface{} {
 	var sortBy string
 	if q.SortBy != sortByUnspecified {
 		sortBys := map[SortBy]string{
@@ -1101,7 +1101,7 @@ func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
 	}
 
 	type queryUsersRequestInternal QueryUsersRequest
-	temp := &struct {
+	return &struct {
 		SortBy string `json:"sortBy,omitempty"`
 		Order  string `json:"order,omitempty"`
 		*queryUsersRequestInternal
@@ -1110,7 +1110,6 @@ func (q *QueryUsersRequest) MarshalJSON() ([]byte, error) {
 		Order:                     order,
 		queryUsersRequestInternal: (*queryUsersRequestInternal)(q),
 	}
-	return json.Marshal(temp)
 }
 
 // SortBy is a field to use for sorting user accounts.
@@ -1148,7 +1147,7 @@ func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (
 	}
 
 	var parsed queryUsersResponse
-	_, err := c.post(ctx, "/accounts:query", query, &parsed)
+	_, err := c.post(ctx, "/accounts:query", query.build(), &parsed)
 	if err != nil {
 		return nil, err
 	}

From 41866c77fbb23363cadcd41b5ff1057e3863040b Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Tue, 25 Nov 2025 20:27:05 +0000
Subject: [PATCH 11/15] add integration tests

---
 integration/auth/tenant_mgt_test.go | 17 ++++++++++++++
 integration/auth/user_mgt_test.go   | 36 +++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/integration/auth/tenant_mgt_test.go b/integration/auth/tenant_mgt_test.go
index a1349d4c..c5ab6de2 100644
--- a/integration/auth/tenant_mgt_test.go
+++ b/integration/auth/tenant_mgt_test.go
@@ -427,6 +427,23 @@ func testTenantAwareUserManagement(t *testing.T, id string) {
 		}
 	})
 
+	t.Run("QueryUsers()", func(t *testing.T) {
+		query := &auth.QueryUsersRequest{
+			Expression: []*auth.Expression{
+				{
+					Email: want.Email,
+				},
+			},
+		}
+		result, err := tenantClient.QueryUsers(context.Background(), query)
+		if err != nil {
+			t.Fatalf("QueryUsers() = %v", err)
+		}
+		if len(result.Users) != 1 || result.Users[0].UID != user.UID {
+			t.Errorf("QueryUsers(email=%s) = %v; want user %s", want.Email, result.Users, user.UID)
+		}
+	})
+
 	t.Run("DeleteUser()", func(t *testing.T) {
 		if err := tenantClient.DeleteUser(context.Background(), user.UID); err != nil {
 			t.Fatalf("DeleteUser() = %v", err)
diff --git a/integration/auth/user_mgt_test.go b/integration/auth/user_mgt_test.go
index cae59097..63b01820 100644
--- a/integration/auth/user_mgt_test.go
+++ b/integration/auth/user_mgt_test.go
@@ -1442,3 +1442,39 @@ func deletePhoneNumberUser(t *testing.T, phoneNumber string) {
 		t.Fatal(err)
 	}
 }
+func TestQueryUsers(t *testing.T) {
+	u1 := newUserWithParams(t)
+	defer deleteUser(u1.UID)
+	u2 := newUserWithParams(t)
+	defer deleteUser(u2.UID)
+
+	// Query by email
+	query := &auth.QueryUsersRequest{
+		Expression: []*auth.Expression{
+			{
+				Email: u1.Email,
+			},
+		},
+	}
+	result, err := client.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() = %v", err)
+	}
+	if len(result.Users) != 1 || result.Users[0].UID != u1.UID {
+		t.Errorf("QueryUsers(email=%s) = %v; want user %s", u1.Email, result.Users, u1.UID)
+	}
+
+	// Query with limit and sort
+	query = &auth.QueryUsersRequest{
+		Limit:  2,
+		SortBy: auth.CreatedAt,
+		Order:  auth.Desc,
+	}
+	result, err = client.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() = %v", err)
+	}
+	if len(result.Users) < 2 {
+		t.Errorf("QueryUsers(limit=2) = %d users; want >= 2", len(result.Users))
+	}
+}

From 5c560ea6ab4834891d20f5057c1af7725a470522 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Thu, 27 Nov 2025 19:27:25 +0000
Subject: [PATCH 12/15] set returnUserInfo to true when undefined

---
 auth/tenant_mgt_test.go           |  3 ++-
 auth/user_mgt.go                  | 10 ++++++--
 auth/user_mgt_test.go             | 38 ++++++++++++++++++++++++++++---
 integration/auth/user_mgt_test.go |  2 +-
 4 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/auth/tenant_mgt_test.go b/auth/tenant_mgt_test.go
index bc7d814b..539d24e5 100644
--- a/auth/tenant_mgt_test.go
+++ b/auth/tenant_mgt_test.go
@@ -103,8 +103,9 @@ func TestTenantQueryUsers(t *testing.T) {
 		t.Fatalf("Failed to create tenant client: %v", err)
 	}
 
+	returnUserInfo := true
 	query := &QueryUsersRequest{
-		ReturnUserInfo: true,
+		ReturnUserInfo: &returnUserInfo,
 	}
 
 	_, err = tenantClient.QueryUsers(context.Background(), query)
diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index 767b6bf9..b8a513ac 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1068,7 +1068,7 @@ type Expression struct {
 
 // QueryUsersRequest is the request structure for the accounts:query endpoint.
 type QueryUsersRequest struct {
-	ReturnUserInfo bool          `json:"returnUserInfo"`
+	ReturnUserInfo *bool         `json:"returnUserInfo,omitempty"`
 	Limit          int64         `json:"limit,string,omitempty"`
 	Offset         int64         `json:"offset,string,omitempty"`
 	SortBy         SortBy        `json:"-"`
@@ -1101,6 +1101,12 @@ func (q *QueryUsersRequest) build() interface{} {
 	}
 
 	type queryUsersRequestInternal QueryUsersRequest
+	internal := (*queryUsersRequestInternal)(q)
+	if internal.ReturnUserInfo == nil {
+		t := true
+		internal.ReturnUserInfo = &t
+	}
+
 	return &struct {
 		SortBy string `json:"sortBy,omitempty"`
 		Order  string `json:"order,omitempty"`
@@ -1108,7 +1114,7 @@ func (q *QueryUsersRequest) build() interface{} {
 	}{
 		SortBy:                    sortBy,
 		Order:                     order,
-		queryUsersRequestInternal: (*queryUsersRequestInternal)(q),
+		queryUsersRequestInternal: internal,
 	}
 }
 
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 918a2a4f..0a2e26da 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -1942,8 +1942,9 @@ func TestQueryUsers(t *testing.T) {
 	s := echoServer([]byte(resp), t)
 	defer s.Close()
 
-	query := &QueryUsersRequest{
-		ReturnUserInfo: true,
+	returnUserInfo := true
+	query := &QueryUsersRequest {
+		ReturnUserInfo: &returnUserInfo,
 		Limit:          1,
 		SortBy:         UserEmail,
 		Order:          Asc,
@@ -1987,8 +1988,9 @@ func TestQueryUsersError(t *testing.T) {
 	defer s.Close()
 	s.Status = http.StatusBadRequest
 
+	returnUserInfo := true
 	query := &QueryUsersRequest{
-		ReturnUserInfo: true,
+		ReturnUserInfo: &returnUserInfo,
 		Limit:          1,
 		SortBy:         UserEmail,
 		Order:          Asc,
@@ -2505,3 +2507,33 @@ func echoServer(resp interface{}, t *testing.T) *mockAuthServer {
 func (s *mockAuthServer) Close() {
 	s.Srv.Close()
 }
+
+func TestQueryUsersDefaultReturnUserInfo(t *testing.T) {
+	resp := `{
+		"userInfo": [{
+			"localId": "testuser"
+		}],
+		"recordsCount": "1"
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+
+	// ReturnUserInfo is nil, should default to true in build()
+	query := &QueryUsersRequest{
+		Limit: 1,
+	}
+
+	_, err := s.Client.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() = %v", err)
+	}
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(s.Rbody, &got); err != nil {
+		t.Fatal(err)
+	}
+
+	if got["returnUserInfo"] != true {
+		t.Errorf("QueryUsers() request[\"returnUserInfo\"] = %v; want true", got["returnUserInfo"])
+	}
+}
diff --git a/integration/auth/user_mgt_test.go b/integration/auth/user_mgt_test.go
index 63b01820..399c3fe2 100644
--- a/integration/auth/user_mgt_test.go
+++ b/integration/auth/user_mgt_test.go
@@ -1461,7 +1461,7 @@ func TestQueryUsers(t *testing.T) {
 		t.Fatalf("QueryUsers() = %v", err)
 	}
 	if len(result.Users) != 1 || result.Users[0].UID != u1.UID {
-		t.Errorf("QueryUsers(email=%s) = %v; want user %s", u1.Email, result.Users, u1.UID)
+		t.Errorf("QueryUsers(uid=%s) = %v; want user %s", u1.UID, result.Users, u1.UID)
 	}
 
 	// Query with limit and sort

From aeef2108eb6d83bd7b397862bed9296d608cbe3b Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Thu, 27 Nov 2025 19:53:29 +0000
Subject: [PATCH 13/15] fix lint erros

---
 auth/user_mgt_test.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 0a2e26da..317230d7 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -1943,7 +1943,7 @@ func TestQueryUsers(t *testing.T) {
 	defer s.Close()
 
 	returnUserInfo := true
-	query := &QueryUsersRequest {
+	query := &QueryUsersRequest{
 		ReturnUserInfo: &returnUserInfo,
 		Limit:          1,
 		SortBy:         UserEmail,

From 98554a5175a113ba9824dc6e3f18934d51dc28f1 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Thu, 27 Nov 2025 22:01:35 +0000
Subject: [PATCH 14/15] cleanup debug logs

---
 auth/user_mgt.go        |  4 ---
 auth/user_mgt_test.go   | 60 ++++++++++++++++++++---------------------
 internal/http_client.go |  2 --
 3 files changed, 30 insertions(+), 36 deletions(-)

diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index b8a513ac..78213626 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1158,8 +1158,6 @@ func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (
 		return nil, err
 	}
 
-	//log.Printf("QueryUsers() with response = %d, %d", parsed.Count, len(parsed.Users))
-
 	var userRecords []*UserRecord
 	for _, user := range parsed.Users {
 		userRecord, err := user.makeUserRecord()
@@ -1525,8 +1523,6 @@ func (c *baseClient) post(
 		URL:    url,
 		Body:   internal.NewJSONEntity(payload),
 	}
-	//log.Printf("%+v \n", req.Body)
-	//log.Printf("%+v \n", resp)
 	return c.httpClient.DoAndUnmarshal(ctx, req, resp)
 }
 
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 317230d7..2168bb6d 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -2048,6 +2048,36 @@ func TestQueryUsersMalformedLastRefreshTimestamp(t *testing.T) {
 	}
 }
 
+func TestQueryUsersDefaultReturnUserInfo(t *testing.T) {
+	resp := `{
+		"userInfo": [{
+			"localId": "testuser"
+		}],
+		"recordsCount": "1"
+	}`
+	s := echoServer([]byte(resp), t)
+	defer s.Close()
+
+	// ReturnUserInfo is nil, should default to true in build()
+	query := &QueryUsersRequest{
+		Limit: 1,
+	}
+
+	_, err := s.Client.QueryUsers(context.Background(), query)
+	if err != nil {
+		t.Fatalf("QueryUsers() = %v", err)
+	}
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(s.Rbody, &got); err != nil {
+		t.Fatal(err)
+	}
+
+	if got["returnUserInfo"] != true {
+		t.Errorf("QueryUsers() request[\"returnUserInfo\"] = %v; want true", got["returnUserInfo"])
+	}
+}
+
 func TestMakeExportedUser(t *testing.T) {
 	queryResponse := &userQueryResponse{
 		UID:                "testuser",
@@ -2507,33 +2537,3 @@ func echoServer(resp interface{}, t *testing.T) *mockAuthServer {
 func (s *mockAuthServer) Close() {
 	s.Srv.Close()
 }
-
-func TestQueryUsersDefaultReturnUserInfo(t *testing.T) {
-	resp := `{
-		"userInfo": [{
-			"localId": "testuser"
-		}],
-		"recordsCount": "1"
-	}`
-	s := echoServer([]byte(resp), t)
-	defer s.Close()
-
-	// ReturnUserInfo is nil, should default to true in build()
-	query := &QueryUsersRequest{
-		Limit: 1,
-	}
-
-	_, err := s.Client.QueryUsers(context.Background(), query)
-	if err != nil {
-		t.Fatalf("QueryUsers() = %v", err)
-	}
-
-	var got map[string]interface{}
-	if err := json.Unmarshal(s.Rbody, &got); err != nil {
-		t.Fatal(err)
-	}
-
-	if got["returnUserInfo"] != true {
-		t.Errorf("QueryUsers() request[\"returnUserInfo\"] = %v; want true", got["returnUserInfo"])
-	}
-}
diff --git a/internal/http_client.go b/internal/http_client.go
index d29af2f5..9d1257bc 100644
--- a/internal/http_client.go
+++ b/internal/http_client.go
@@ -167,8 +167,6 @@ func (c *HTTPClient) DoAndUnmarshal(ctx context.Context, req *Request, v interfa
 		return nil, err
 	}
 
-	//log.Printf("%+v \n", string(resp.Body))
-
 	if v != nil {
 		if err := json.Unmarshal(resp.Body, v); err != nil {
 			return nil, fmt.Errorf("error while parsing response: %v", err)

From c3ff5f71ce3a7752c309072e75a66887480896f8 Mon Sep 17 00:00:00 2001
From: Lahiru Maramba <llahiru@gmail.com>
Date: Thu, 27 Nov 2025 22:44:47 +0000
Subject: [PATCH 15/15] Update documentation and added validation

---
 AGENTS.md             |  1 +
 auth/user_mgt.go      | 69 ++++++++++++++++++++++++++++++++++++-------
 auth/user_mgt_test.go | 62 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 121 insertions(+), 11 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e6b95039..b2d6d89a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,6 +64,7 @@ The Firebase Admin Go SDK enables server-side (backend) applications to interact
 
 -   **DO:** Use the centralized HTTP client in `internal/http_client.go` for all network calls.
 -   **DO:** Pass `context.Context` as the first argument to all functions that perform I/O or other blocking operations.
+-   **DO:** Run `go fmt` after implementing a change and fix any linting errors.
 -   **DON'T:** Expose types or functions from the `internal/` directory in the public API.
 -   **DON'T:** Introduce new third-party dependencies without a strong, documented justification and team consensus.
 
diff --git a/auth/user_mgt.go b/auth/user_mgt.go
index 78213626..3b80e4b4 100644
--- a/auth/user_mgt.go
+++ b/auth/user_mgt.go
@@ -1048,7 +1048,7 @@ func (c *baseClient) GetUsers(
 	return &GetUsersResult{userRecords, notFound}, nil
 }
 
-// QueryUserInfoResponse is the response structure for the accounts:query endpoint.
+// QueryUserInfoResponse is the response structure for the QueryUsers function.
 type QueryUserInfoResponse struct {
 	Users []*UserRecord
 	Count int64
@@ -1060,21 +1060,38 @@ type queryUsersResponse struct {
 }
 
 // Expression is a query condition used to filter results.
+//
+// Only one of Email, PhoneNumber, or UID should be specified.
+// If more than one is specified, only the first (in the order of Email, PhoneNumber, UID) will be applied.
 type Expression struct {
-	Email       string `json:"email,omitempty"`
-	UID         string `json:"userId,omitempty"`
+	// Email is a case insensitive string that the account's email should match.
+	Email string `json:"email,omitempty"`
+	// PhoneNumber is a string that the account's phone number should match.
 	PhoneNumber string `json:"phoneNumber,omitempty"`
+	// UID is a string that the account's local ID should match.
+	UID string `json:"userId,omitempty"`
 }
 
-// QueryUsersRequest is the request structure for the accounts:query endpoint.
+// QueryUsersRequest is the request structure for the QueryUsers function.
 type QueryUsersRequest struct {
-	ReturnUserInfo *bool         `json:"returnUserInfo,omitempty"`
-	Limit          int64         `json:"limit,string,omitempty"`
-	Offset         int64         `json:"offset,string,omitempty"`
-	SortBy         SortBy        `json:"-"`
-	Order          Order         `json:"-"`
-	TenantID       string        `json:"tenantId,omitempty"`
-	Expression     []*Expression `json:"expression,omitempty"`
+	// ReturnUserInfo indicates whether to return the accounts matching the query.
+	// If false, only the count of accounts matching the query will be returned.
+	// Defaults to true.
+	ReturnUserInfo *bool `json:"returnUserInfo,omitempty"`
+	// Limit is the maximum number of accounts to return with an upper limit of 500.
+	// Defaults to 500. Only valid when ReturnUserInfo is set to true.
+	Limit int64 `json:"limit,string,omitempty"`
+	// Offset is the number of accounts to skip from the beginning of matching records.
+	// Only valid when ReturnUserInfo is set to true.
+	Offset int64 `json:"offset,string,omitempty"`
+	// SortBy is the field to use for sorting user accounts.
+	SortBy SortBy `json:"-"`
+	// Order is the order for sorting query results.
+	Order Order `json:"-"`
+	// TenantID is the ID of the tenant to which the result is scoped.
+	TenantID string `json:"tenantId,omitempty"`
+	// Expression is a list of query conditions used to filter results.
+	Expression []*Expression `json:"expression,omitempty"`
 }
 
 // build builds the query request (for internal use only).
@@ -1118,6 +1135,33 @@ func (q *QueryUsersRequest) build() interface{} {
 	}
 }
 
+func (q *QueryUsersRequest) validate() error {
+	if q.Limit != 0 && (q.Limit < 1 || q.Limit > 500) {
+		return fmt.Errorf("limit must be between 1 and 500")
+	}
+	if q.Offset < 0 {
+		return fmt.Errorf("offset must be non-negative")
+	}
+	for _, exp := range q.Expression {
+		if exp.Email != "" {
+			if err := validateEmail(exp.Email); err != nil {
+				return err
+			}
+		}
+		if exp.PhoneNumber != "" {
+			if err := validatePhone(exp.PhoneNumber); err != nil {
+				return err
+			}
+		}
+		if exp.UID != "" {
+			if err := validateUID(exp.UID); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
 // SortBy is a field to use for sorting user accounts.
 type SortBy int
 
@@ -1151,6 +1195,9 @@ func (c *baseClient) QueryUsers(ctx context.Context, query *QueryUsersRequest) (
 	if query == nil {
 		return nil, fmt.Errorf("query request must not be nil")
 	}
+	if err := query.validate(); err != nil {
+		return nil, err
+	}
 
 	var parsed queryUsersResponse
 	_, err := c.post(ctx, "/accounts:query", query.build(), &parsed)
diff --git a/auth/user_mgt_test.go b/auth/user_mgt_test.go
index 2168bb6d..094716c2 100644
--- a/auth/user_mgt_test.go
+++ b/auth/user_mgt_test.go
@@ -2078,6 +2078,68 @@ func TestQueryUsersDefaultReturnUserInfo(t *testing.T) {
 	}
 }
 
+func TestQueryUsersValidation(t *testing.T) {
+	s := echoServer([]byte("{}"), t)
+	defer s.Close()
+
+	tests := []struct {
+		name  string
+		query *QueryUsersRequest
+	}{
+		{
+			name: "Invalid Limit Low",
+			query: &QueryUsersRequest{
+				Limit: -1,
+			},
+		},
+		{
+			name: "Invalid Limit High",
+			query: &QueryUsersRequest{
+				Limit: 501,
+			},
+		},
+		{
+			name: "Invalid Offset",
+			query: &QueryUsersRequest{
+				Offset: -1,
+			},
+		},
+		{
+			name: "Invalid Email in Expression",
+			query: &QueryUsersRequest{
+				Expression: []*Expression{
+					{Email: "invalid-email"},
+				},
+			},
+		},
+		{
+			name: "Invalid Phone in Expression",
+			query: &QueryUsersRequest{
+				Expression: []*Expression{
+					{PhoneNumber: "invalid-phone"},
+				},
+			},
+		},
+		{
+			name: "Invalid UID in Expression",
+			query: &QueryUsersRequest{
+				Expression: []*Expression{
+					{UID: string(make([]byte, 129))},
+				},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := s.Client.QueryUsers(context.Background(), tt.query)
+			if err == nil {
+				t.Errorf("QueryUsers() with %s; want error, got nil", tt.name)
+			}
+		})
+	}
+}
+
 func TestMakeExportedUser(t *testing.T) {
 	queryResponse := &userQueryResponse{
 		UID:                "testuser",