feat(api): return accurate contacts total for server pagination

Extend the contact repository/service/handler so GET /v1/contacts returns
a top-level total count for the same user/query filter, independent of
skip/limit, enabling true server-side pagination.

- add ContactRepository.Count reusing a shared scopedContactQuery helper
  so Index and Count filters can never drift; Count ignores limit/offset
- add ContactService.Count and handler responseOKWithTotal; Index returns total
- add Total to responses.ContactsResponse and regenerate Swagger
- sanitize parsed CSV rows before validation so CSV and JSON accept the
  same phone/email formats; drop the now-redundant re-sanitize on upload
- assert Scan error behaviour instead of the unexported stacktrace type
- tests for count filter parity, total propagation, and CSV sanitization

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: AchoArnold

api/docs/docs.go

@@ -249,7 +249,7 @@ const docTemplate = `{
                         "ApiKeyAuth": []
                     }
                 ],
-                "description": "Returns the paginated list of contacts for the authenticated user.",
+                "description": "Returns the paginated list of contacts for the authenticated user. The top-level \"total\" field is the number of contacts matching the query filter, independent of skip/limit, so clients can drive server-side pagination.",
                 "consumes": [
                     "application/json"
                 ],
@@ -5257,7 +5257,8 @@ const docTemplate = `{
             "required": [
                 "data",
                 "message",
-                "status"
+                "status",
+                "total"
             ],
             "properties": {
                 "data": {
@@ -5273,6 +5274,11 @@ const docTemplate = `{
                 "status": {
                     "type": "string",
                     "example": "success"
+                },
+                "total": {
+                    "description": "Total is the number of contacts matching the request filter for the\nuser, independent of the pagination skip/limit applied to Data.",
+                    "type": "integer",
+                    "example": 57
                 }
             }
         },

api/docs/swagger.json

@@ -246,7 +246,7 @@
                         "ApiKeyAuth": []
                     }
                 ],
-                "description": "Returns the paginated list of contacts for the authenticated user.",
+                "description": "Returns the paginated list of contacts for the authenticated user. The top-level \"total\" field is the number of contacts matching the query filter, independent of skip/limit, so clients can drive server-side pagination.",
                 "consumes": [
                     "application/json"
                 ],
@@ -5254,7 +5254,8 @@
             "required": [
                 "data",
                 "message",
-                "status"
+                "status",
+                "total"
             ],
             "properties": {
                 "data": {
@@ -5270,6 +5271,11 @@
                 "status": {
                     "type": "string",
                     "example": "success"
+                },
+                "total": {
+                    "description": "Total is the number of contacts matching the request filter for the\nuser, independent of the pagination skip/limit applied to Data.",
+                    "type": "integer",
+                    "example": 57
                 }
             }
         },

api/docs/swagger.yaml

@@ -1235,10 +1235,17 @@ definitions:
       status:
         example: success
         type: string
+      total:
+        description: |-
+          Total is the number of contacts matching the request filter for the
+          user, independent of the pagination skip/limit applied to Data.
+        example: 57
+        type: integer
     required:
     - data
     - message
     - status
+    - total
     type: object
   responses.DiscordResponse:
     properties:
@@ -1883,6 +1890,8 @@ paths:
       consumes:
       - application/json
       description: Returns the paginated list of contacts for the authenticated user.
+        The top-level "total" field is the number of contacts matching the query filter,
+        independent of skip/limit, so clients can drive server-side pagination.
       parameters:
       - description: number of contacts to skip
         in: query

api/pkg/entities/contact_test.go

@@ -1,7 +1,6 @@
 package entities
 
 import (
-	"reflect"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -47,6 +46,5 @@ func TestContactProperties_ScanUnsupportedType(t *testing.T) {
 	err := scanned.Scan(123)
 
 	assert.Error(t, err)
-	assert.Equal(t, "*stacktrace.stacktrace", reflect.TypeOf(err).String())
 	assert.Contains(t, err.Error(), "unsupported type [int] for ContactProperties")
 }

api/pkg/handlers/contact_handler.go

@@ -49,7 +49,7 @@ func (h *ContactHandler) RegisterRoutes(router fiber.Router, middlewares ...fibe
 
 // Index lists contacts for the authenticated user.
 // @Summary      List contacts
-// @Description  Returns the paginated list of contacts for the authenticated user.
+// @Description  Returns the paginated list of contacts for the authenticated user. The top-level "total" field is the number of contacts matching the query filter, independent of skip/limit, so clients can drive server-side pagination.
 // @Security	 ApiKeyAuth
 // @Tags         Contacts
 // @Accept       json
@@ -80,13 +80,20 @@ func (h *ContactHandler) Index(c fiber.Ctx) error {
 	}
 
 	userID := h.userIDFomContext(c)
-	contacts, err := h.service.Index(ctx, userID, sanitized.ToIndexParams())
+	params := sanitized.ToIndexParams()
+	contacts, err := h.service.Index(ctx, userID, params)
 	if err != nil {
 		ctxLogger.Error(stacktrace.Propagatef(err, "cannot list contacts for user [%s]", userID))
 		return h.responseInternalServerError(c)
 	}
 
-	return h.responseOK(c, fmt.Sprintf("fetched %d %s", len(*contacts), h.pluralize("contact", len(*contacts))), contacts)
+	total, err := h.service.Count(ctx, userID, params)
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot count contacts for user [%s]", userID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseOKWithTotal(c, fmt.Sprintf("fetched %d %s", len(*contacts), h.pluralize("contact", len(*contacts))), contacts, total)
 }
 
 // Store creates one or many contacts.
@@ -160,7 +167,9 @@ func (h *ContactHandler) Upload(c fiber.Ctx) error {
 		return h.responseUnprocessableEntity(c, errors, "validation errors while importing contacts")
 	}
 
-	request := (requests.ContactStoreRequest{Contacts: items}).Sanitize()
+	// items are already sanitized by ValidateUpload (SanitizeContactItem), so
+	// build the persistable records directly without re-sanitizing.
+	request := requests.ContactStoreRequest{Contacts: items}
 	contacts := request.ToContacts(userID)
 	if err = h.service.CreateMany(ctx, userID, contacts); err != nil {
 		ctxLogger.Error(stacktrace.Propagatef(err, "cannot import [%d] contacts for user [%s]", len(contacts), userID))

api/pkg/handlers/contact_handler_test.go

@@ -41,12 +41,15 @@ type contactHandlerFakeRepo struct {
 	updated     []*entities.Contact
 	deleted     []deletedContact
 	indexParams []repositories.IndexParams
+	countParams []repositories.IndexParams
 	loadCalls   []loadedContact
 
 	loadResult  *entities.Contact
 	loadErr     error
 	indexResult []entities.Contact
 	indexErr    error
+	countResult int64
+	countErr    error
 	storeErr    error
 	updateErr   error
 	deleteErr   error
@@ -109,6 +112,16 @@ func (r *contactHandlerFakeRepo) Index(_ context.Context, _ entities.UserID, par
 	return &out, nil
 }
 
+func (r *contactHandlerFakeRepo) Count(_ context.Context, _ entities.UserID, params repositories.IndexParams) (int64, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.countParams = append(r.countParams, params)
+	if r.countErr != nil {
+		return 0, r.countErr
+	}
+	return r.countResult, nil
+}
+
 func (r *contactHandlerFakeRepo) FetchAll(context.Context, entities.UserID) (*[]entities.Contact, error) {
 	out := []entities.Contact{}
 	return &out, nil
@@ -157,6 +170,7 @@ type contactHandlerPayload struct {
 	Status  string          `json:"status"`
 	Message string          `json:"message"`
 	Data    json.RawMessage `json:"data"`
+	Total   int64           `json:"total"`
 }
 
 func decodeContactHandlerPayload(t *testing.T, resp *http.Response) contactHandlerPayload {
@@ -467,6 +481,54 @@ func TestContactHandler_Index_ConvertsQueryAndScopesToUser(t *testing.T) {
 	assert.Contains(t, payload.Message, "1")
 }
 
+func TestContactHandler_Index_ReturnsServerTotalIndependentOfPageLength(t *testing.T) {
+	repo := &contactHandlerFakeRepo{
+		indexResult: []entities.Contact{
+			{ID: uuid.New(), UserID: contactHandlerTestUserID, Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},
+			{ID: uuid.New(), UserID: contactHandlerTestUserID, Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},
+		},
+		countResult: 57,
+	}
+	app := newContactHandlerTestApp(repo)
+
+	values := url.Values{}
+	values.Set("skip", "5")
+	values.Set("limit", "25")
+	values.Set("query", "ali")
+	req := httptest.NewRequest(http.MethodGet, "/v1/contacts?"+values.Encode(), nil)
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	payload := decodeContactHandlerPayload(t, resp)
+	assert.Equal(t, "success", payload.Status)
+	// total must be the server count, not the length of the returned page.
+	assert.Equal(t, int64(57), payload.Total)
+
+	var data []entities.Contact
+	require.NoError(t, json.Unmarshal(payload.Data, &data))
+	assert.Len(t, data, 2)
+
+	// Count must run with the exact same filter/pagination params as Index.
+	require.Len(t, repo.indexParams, 1)
+	require.Len(t, repo.countParams, 1)
+	assert.Equal(t, repo.indexParams[0], repo.countParams[0])
+	assert.Equal(t, 5, repo.countParams[0].Skip)
+	assert.Equal(t, 25, repo.countParams[0].Limit)
+	assert.Equal(t, "ali", repo.countParams[0].Query)
+}
+
+func TestContactHandler_Index_CountErrorReturnsInternalServerError(t *testing.T) {
+	repo := &contactHandlerFakeRepo{countErr: assert.AnError}
+	app := newContactHandlerTestApp(repo)
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/contacts", nil)
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusInternalServerError, resp.StatusCode)
+}
+
 func TestContactHandler_Index_DefaultsAppliedWhenParamsMissing(t *testing.T) {
 	repo := &contactHandlerFakeRepo{}
 	app := newContactHandlerTestApp(repo)

api/pkg/handlers/handler.go

@@ -97,6 +97,15 @@ func (h *handler) responseOK(c fiber.Ctx, message string, data interface{}) erro
 	})
 }
 
+func (h *handler) responseOKWithTotal(c fiber.Ctx, message string, data interface{}, total int64) error {
+	return c.Status(fiber.StatusOK).JSON(fiber.Map{
+		"status":  "success",
+		"message": message,
+		"data":    data,
+		"total":   total,
+	})
+}
+
 func (h *handler) responseCreated(c fiber.Ctx, message string, data interface{}) error {
 	return c.Status(fiber.StatusCreated).JSON(fiber.Map{
 		"status":  "success",

api/pkg/repositories/contact_repository.go

@@ -21,6 +21,10 @@ type ContactRepository interface {
 	// Index contacts for a user with optional search.
 	Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)
 
+	// Count returns the number of contacts for a user matching the same
+	// name/emails/phone_numbers filter as Index, ignoring pagination.
+	Count(ctx context.Context, userID entities.UserID, params IndexParams) (int64, error)
+
 	// FetchAll returns every contact for a user ordered by updated_at ascending.
 	FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)
 

api/pkg/repositories/gorm_contact_repository.go

@@ -78,28 +78,51 @@ func (repository *gormContactRepository) Load(ctx context.Context, userID entiti
 	return contact, nil
 }
 
-func (repository *gormContactRepository) Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error) {
-	ctx, span := repository.tracer.Start(ctx)
-	defer span.End()
-
-	query := repository.db.WithContext(ctx).Where("user_id = ?", userID)
-	if len(params.Query) > 0 {
-		queryPattern := "%" + params.Query + "%"
-		query = query.Where(
+// scopedContactQuery builds the shared query that scopes contacts to a user and
+// applies the optional name/emails/phone_numbers search filter. Index and Count
+// both build on it so their filters can never drift apart. It sets the model so
+// callers can chain Find or Count without repeating the table.
+func (repository *gormContactRepository) scopedContactQuery(ctx context.Context, userID entities.UserID, query string) *gorm.DB {
+	scoped := repository.db.WithContext(ctx).Model(&entities.Contact{}).Where("user_id = ?", userID)
+	if len(query) > 0 {
+		queryPattern := "%" + query + "%"
+		scoped = scoped.Where(
 			repository.db.WithContext(ctx).Where("name ILIKE ?", queryPattern).
 				Or("array_to_string(emails, ',') ILIKE ?", queryPattern).
 				Or("array_to_string(phone_numbers, ',') ILIKE ?", queryPattern),
 		)
 	}
+	return scoped
+}
+
+func (repository *gormContactRepository) Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error) {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
 
 	contacts := new([]entities.Contact)
-	if err := query.Order("updated_at DESC").Limit(params.Limit).Offset(params.Skip).Find(contacts).Error; err != nil {
+	if err := repository.scopedContactQuery(ctx, userID, params.Query).
+		Order("updated_at DESC").
+		Limit(params.Limit).
+		Offset(params.Skip).
+		Find(contacts).Error; err != nil {
 		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s] with params [%+#v]", userID, params))
 	}
 
 	return contacts, nil
 }
 
+func (repository *gormContactRepository) Count(ctx context.Context, userID entities.UserID, params IndexParams) (int64, error) {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	var count int64
+	if err := repository.scopedContactQuery(ctx, userID, params.Query).Count(&count).Error; err != nil {
+		return 0, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot count contacts for user [%s] with query [%s]", userID, params.Query))
+	}
+
+	return count, nil
+}
+
 func (repository *gormContactRepository) FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error) {
 	ctx, span := repository.tracer.Start(ctx)
 	defer span.End()

api/pkg/repositories/gorm_contact_repository_test.go

@@ -218,6 +218,45 @@ func TestGormContactRepository_Load_ScopesByUserAndContactID(t *testing.T) {
 	assert.Equal(t, 1, statement.args[2])
 }
 
+func TestGormContactRepository_Count_ReusesIndexFilterWithoutPagination(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+
+	total, err := repository.Count(context.Background(), entities.UserID("user-1"), IndexParams{
+		Query: "alice",
+		// Limit/Skip must be ignored by Count.
+		Limit: 20,
+		Skip:  40,
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, int64(0), total)
+
+	statement := lastContactStatement(t, recorder)
+	assert.True(t, strings.HasPrefix(statement.query, `SELECT count(*) FROM "contacts"`))
+	// Count must apply the exact same user + name/emails/phone_numbers filter as Index.
+	assert.Contains(t, statement.query, `WHERE user_id = $1 AND (name ILIKE $2 OR array_to_string(emails, ',') ILIKE $3 OR array_to_string(phone_numbers, ',') ILIKE $4)`)
+	// Count must ignore pagination.
+	assert.NotContains(t, statement.query, "LIMIT")
+	assert.NotContains(t, statement.query, "OFFSET")
+	require.Len(t, statement.args, 4)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+	assert.Equal(t, "%alice%", statement.args[1])
+	assert.Equal(t, "%alice%", statement.args[2])
+	assert.Equal(t, "%alice%", statement.args[3])
+}
+
+func TestGormContactRepository_Count_ScopesByUserWithoutQuery(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+
+	_, err := repository.Count(context.Background(), entities.UserID("user-1"), IndexParams{})
+
+	require.NoError(t, err)
+	statement := lastContactStatement(t, recorder)
+	assert.Equal(t, `SELECT count(*) FROM "contacts" WHERE user_id = $1`, statement.query)
+	require.Len(t, statement.args, 1)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+}
+
 func TestGormContactRepository_Index_FiltersByUserAndQueryAcrossContactFields(t *testing.T) {
 	repository, recorder := newContactTestRepo(t)