From eb90685be6505064df8ff239c077391e806cf060 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 20:59:49 +0300
Subject: [PATCH 01/24] docs: add contacts feature implementation plan

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8dd82cae-8bc6-4eaa-9b90-95073720c577
---
 .../plans/2026-07-19-contacts-feature.md      | 3025 +++++++++++++++++
 1 file changed, 3025 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-19-contacts-feature.md

diff --git a/docs/superpowers/plans/2026-07-19-contacts-feature.md b/docs/superpowers/plans/2026-07-19-contacts-feature.md
new file mode 100644
index 000000000..8a72fe407
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-19-contacts-feature.md
@@ -0,0 +1,3025 @@
+# Contacts Feature Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a Contacts feature (name, emails, phone numbers, free-form properties) with full CRUD + CSV import, and display the resolved contact name instead of the raw phone number on the threads page, using as few DB queries as possible.
+
+**Architecture:** New `Contact` entity + layered backend (handler → service → repository → validator → requests/responses) mirroring existing patterns. Thread-name resolution is opt-in per request and served from a per-user `phone_number → *Contact` map cached in `cache.Cache`, so the common path adds zero DB queries and a name change is a single-row `UPDATE` + cache invalidation. Frontend adds a Pinia store and a Plunk-style Contacts page (Nuxt 4 SPA).
+
+**Tech Stack:** Go (Fiber v3, GORM v1.31.2, lib/pq, nyaruka/phonenumbers, jszwec/csvutil), Nuxt 4 + Pinia + Vuetify 4, Swagger (`swag`), swagger-typescript-api.
+
+## Global Constraints
+
+- Source of truth: `docs/superpowers/specs/2026-07-19-contacts-feature-design.md`. Follow it exactly.
+- Run Go tests with `go test -vet=off ./...` from `api/` (Go 1.26 vet rejects the repo's `stacktrace.Propagate(err, fmt.Sprintf(...))` pattern).
+- Wrap all Go errors with `github.com/NdoleStudio/stacktrace` (`Propagatef` / `PropagateWithCodef`) — never return bare errors.
+- All GORM queries use `repository.db.WithContext(ctx)`. No raw SQL.
+- Register Fiber routes via the `h.register(router, fiber.MethodX, path, middlewares, route)` helper (Fiber v3), not `Get`/`Post` directly.
+- Contacts are global to the user account. **No** uniqueness constraint on phone numbers; **no** `contact_phone_numbers` lookup table.
+- On phone-number collision across contacts, the **most recently updated** contact wins for display.
+- Thread-name resolution is **opt-in** via `?contacts=true` (default off).
+- Create endpoint accepts one or many; batch capped at **≤ 1000** contacts; cache invalidated **once** after the batch commits.
+- CSV import is **CSV only** — Excel/XLSX is not supported for contacts. Max 500 KB, ≤ 1000 rows.
+- `pq.StringArray` with `gorm:"type:text[]" swaggertype:"array,string"` for array fields (convention from `phone_api_key.go`/`webhook.go`).
+- Web conventions: every `VDialog` has `opacity="0.9"` and a Close button with `color="warning"`; hyperlinks get `text-decoration-none hover:text-decoration-underline`; destructure filters from `useFilters()` in `<script setup>` and use directly in the template; no glowing gradient text off the homepage; Vuetify 4 typography classes (`text-headline-large`, `text-title-large`, `text-display-large`, etc.); in `useApi` `onRequest`, `options.headers` is a `Headers` instance — use `.set()`.
+- Regenerate Swagger after API annotation changes: `cd api && swag init --requiredByDefault --parseDependency --parseInternal`.
+- Regenerate web API models after Swagger changes: `cd web && pnpm api:models`.
+
+---
+
+## File Structure
+
+Backend (`api/`):
+- `pkg/entities/contact.go` — `Contact` entity + `ContactProperties` custom jsonb type (Valuer/Scanner).
+- `pkg/entities/contact_test.go` — round-trip tests for `ContactProperties`.
+- `pkg/entities/message_thread.go` — add non-persisted `ContactDetails *Contact` field.
+- `pkg/repositories/contact_repository.go` — `ContactRepository` interface + param structs.
+- `pkg/repositories/gorm_contact_repository.go` — GORM implementation.
+- `pkg/repositories/gorm_contact_repository_test.go` — repository tests.
+- `pkg/requests/contact_store.go` — create-many request + per-item `ContactItem`.
+- `pkg/requests/contact_update.go` — update request.
+- `pkg/requests/contact_index.go` — list/search request.
+- `pkg/responses/*` — reuse existing generic OK/Created responses (no new file needed).
+- `pkg/validators/contact_handler_validator.go` — validates store/update/index + CSV parse.
+- `pkg/services/contact_service.go` — CRUD + contact-map build + cache invalidation.
+- `pkg/services/contact_service_test.go` — service tests.
+- `pkg/handlers/contact_handler.go` — HTTP handlers + `RegisterRoutes`.
+- `pkg/services/message_thread_service.go` — extend `GetThreads` to attach `ContactDetails`.
+- `pkg/requests/message_thread_index_request.go` — add `Contacts` query param.
+- `pkg/di/container.go` — wire repo/service/validator/handler, AutoMigrate, register routes.
+
+Frontend (`web/`):
+- `app/stores/contacts.ts` — Pinia store.
+- `app/pages/contacts/index.vue` — Plunk-style Contacts page + dialogs.
+- `app/stores/threads.ts` — pass `contacts: true`.
+- `app/components/MessageThread.vue`, `app/components/MessageThreadHeader.vue` — render resolved name.
+- default layout — add Contacts nav link.
+- `shared/types/api` — regenerated from Swagger.
+- `public/templates/httpsms-contacts.csv` — CSV template.
+
+---
+
+### Task 1: Contact entity + ContactProperties custom type
+
+**Files:**
+- Create: `api/pkg/entities/contact.go`
+- Create: `api/pkg/entities/contact_test.go`
+
+**Interfaces:**
+- Produces: `entities.Contact` struct; `entities.ContactProperties` (`map[string]string`) implementing `driver.Valuer` and `sql.Scanner`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `api/pkg/entities/contact_test.go`:
+
+```go
+package entities
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestContactProperties_ValueScanRoundTrip(t *testing.T) {
+	cases := []ContactProperties{
+		nil,
+		{},
+		{"company": "Acme", "role": "CTO"},
+	}
+
+	for _, original := range cases {
+		value, err := original.Value()
+		assert.Nil(t, err)
+
+		var scanned ContactProperties
+		assert.Nil(t, scanned.Scan(value))
+
+		if len(original) == 0 {
+			assert.Equal(t, 0, len(scanned))
+			continue
+		}
+		assert.Equal(t, original, scanned)
+	}
+}
+
+func TestContactProperties_ScanFromString(t *testing.T) {
+	var scanned ContactProperties
+	assert.Nil(t, scanned.Scan(`{"k":"v"}`))
+	assert.Equal(t, ContactProperties{"k": "v"}, scanned)
+}
+
+func TestContactProperties_ScanNil(t *testing.T) {
+	var scanned ContactProperties
+	assert.Nil(t, scanned.Scan(nil))
+	assert.Equal(t, 0, len(scanned))
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd api && go test -vet=off ./pkg/entities/ -run TestContactProperties`
+Expected: FAIL / build error — `Contact`/`ContactProperties` undefined.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `api/pkg/entities/contact.go`:
+
+```go
+package entities
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+)
+
+// ContactProperties is a free-form key/value map persisted as a jsonb column.
+type ContactProperties map[string]string
+
+// Value implements driver.Valuer, serializing the map to JSON bytes.
+func (p ContactProperties) Value() (driver.Value, error) {
+	if p == nil {
+		return []byte("{}"), nil
+	}
+	data, err := json.Marshal(p)
+	if err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+// Scan implements sql.Scanner, deserializing jsonb bytes/string into the map.
+func (p *ContactProperties) Scan(src any) error {
+	if src == nil {
+		*p = ContactProperties{}
+		return nil
+	}
+
+	var data []byte
+	switch value := src.(type) {
+	case []byte:
+		data = value
+	case string:
+		data = []byte(value)
+	default:
+		return fmt.Errorf("unsupported type [%T] for ContactProperties", src)
+	}
+
+	if len(data) == 0 {
+		*p = ContactProperties{}
+		return nil
+	}
+
+	result := ContactProperties{}
+	if err := json.Unmarshal(data, &result); err != nil {
+		return err
+	}
+	*p = result
+	return nil
+}
+
+// Contact represents a saved contact belonging to a user.
+type Contact struct {
+	ID           uuid.UUID         `json:"id" gorm:"primaryKey;type:uuid;" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`
+	UserID       UserID            `json:"user_id" gorm:"index" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`
+	Name         string            `json:"name" example:"Alice Smith"`
+	Emails       pq.StringArray    `json:"emails" gorm:"type:text[]" swaggertype:"array,string" example:"alice@example.com"`
+	PhoneNumbers pq.StringArray    `json:"phone_numbers" gorm:"type:text[]" swaggertype:"array,string" example:"+18005550199,+18005550100"`
+	Properties   ContactProperties `json:"properties" gorm:"type:jsonb" swaggertype:"object,string"`
+	CreatedAt    time.Time         `json:"created_at" example:"2022-06-05T14:26:02.302718+03:00"`
+	UpdatedAt    time.Time         `json:"updated_at" example:"2022-06-05T14:26:02.302718+03:00"`
+}
+
+// TableName overrides the table name used by Contact.
+func (Contact) TableName() string {
+	return "contacts"
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd api && go test -vet=off ./pkg/entities/ -run TestContactProperties`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add api/pkg/entities/contact.go api/pkg/entities/contact_test.go
+git commit -m "feat(api): add Contact entity and ContactProperties jsonb type"
+```
+
+---
+
+### Task 2: MessageThread ContactDetails field + AutoMigrate
+
+**Files:**
+- Modify: `api/pkg/entities/message_thread.go`
+- Modify: `api/pkg/di/container.go` (AutoMigrate block ~L413)
+
+**Interfaces:**
+- Produces: `entities.MessageThread.ContactDetails *Contact` (JSON `contact_details`, `gorm:"-"`), `contacts` table auto-migrated.
+
+- [ ] **Step 1: Add the non-persisted field**
+
+In `api/pkg/entities/message_thread.go`, add after the `OrderTimestamp` field inside the `MessageThread` struct:
+
+```go
+	// ContactDetails is resolved at read time and never persisted.
+	ContactDetails *Contact `json:"contact_details,omitempty" gorm:"-"`
+```
+
+- [ ] **Step 2: Register AutoMigrate**
+
+In `api/pkg/di/container.go`, immediately after the `&entities.PhoneAPIKey{}` AutoMigrate block (~L413-415), add:
+
+```go
+	if err = db.AutoMigrate(&entities.Contact{}); err != nil {
+		container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.Contact{}))
+	}
+```
+
+- [ ] **Step 3: Build to verify it compiles**
+
+Run: `cd api && go build ./...`
+Expected: builds with no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add api/pkg/entities/message_thread.go api/pkg/di/container.go
+git commit -m "feat(api): add non-persisted ContactDetails on MessageThread and migrate contacts table"
+```
+
+---
+
+### Task 3: ContactRepository interface + GORM implementation
+
+**Files:**
+- Create: `api/pkg/repositories/contact_repository.go`
+- Create: `api/pkg/repositories/gorm_contact_repository.go`
+- Create: `api/pkg/repositories/gorm_contact_repository_test.go`
+
+**Interfaces:**
+- Consumes: `entities.Contact`, `repositories.IndexParams`, `repositories.ErrCodeNotFound`.
+- Produces: `repositories.ContactRepository` with methods:
+  - `Store(ctx context.Context, contacts []*entities.Contact) error`
+  - `Update(ctx context.Context, contact *entities.Contact) error`
+  - `Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)`
+  - `Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)`
+  - `FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)` (ordered `updated_at ASC` for tie-break)
+  - `Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error`
+  - `DeleteAllForUser(ctx context.Context, userID entities.UserID) error`
+  - Constructor: `NewGormContactRepository(logger, tracer, db) ContactRepository`
+
+- [ ] **Step 1: Write the interface**
+
+Create `api/pkg/repositories/contact_repository.go`:
+
+```go
+package repositories
+
+import (
+	"context"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/google/uuid"
+)
+
+// ContactRepository loads and persists an entities.Contact
+type ContactRepository interface {
+	// Store one or many new entities.Contact
+	Store(ctx context.Context, contacts []*entities.Contact) error
+
+	// Update an existing entities.Contact
+	Update(ctx context.Context, contact *entities.Contact) error
+
+	// Load a contact by ID for a user
+	Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)
+
+	// Index contacts for a user with optional search
+	Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)
+
+	// FetchAll returns every contact for a user ordered by updated_at ascending
+	FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)
+
+	// Delete a contact by ID for a user
+	Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error
+
+	// DeleteAllForUser deletes all contacts for a user
+	DeleteAllForUser(ctx context.Context, userID entities.UserID) error
+}
+```
+
+- [ ] **Step 2: Write the failing test**
+
+Create `api/pkg/repositories/gorm_contact_repository_test.go`. Reuse the SQL-capturing conn-pool mock pattern already defined in `api/pkg/repositories/gorm_message_thread_repository_test.go` (the `messageThreadTestConnPool`, `messageThreadTestLogger`, and the `postgres.New(postgres.Config{Conn: ...})` DryRun setup). Add these focused tests:
+
+```go
+package repositories
+
+import (
+	"context"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+func newContactTestRepo(t *testing.T) (ContactRepository, *messageThreadTestConnPool) {
+	pool := &messageThreadTestConnPool{}
+	db, err := gorm.Open(
+		postgres.New(postgres.Config{Conn: pool, WithoutReturning: true}),
+		&gorm.Config{DisableAutomaticPing: true},
+	)
+	require.NoError(t, err)
+	logger := &messageThreadTestLogger{}
+	return NewGormContactRepository(logger, telemetry.NewOtelLogger("test", logger), db), pool
+}
+
+func TestGormContactRepository_Index_FiltersByUserAndQuery(t *testing.T) {
+	repo, _ := newContactTestRepo(t)
+
+	_, err := repo.Index(context.Background(), entities.UserID("user-1"), IndexParams{Query: "alice", Limit: 20, Skip: 0})
+	assert.Nil(t, err)
+}
+
+func TestGormContactRepository_FetchAll_OrdersByUpdatedAtAsc(t *testing.T) {
+	repo, _ := newContactTestRepo(t)
+
+	_, err := repo.FetchAll(context.Background(), entities.UserID("user-1"))
+	assert.Nil(t, err)
+}
+
+func TestGormContactRepository_Store_BuildsContact(t *testing.T) {
+	repo, _ := newContactTestRepo(t)
+
+	err := repo.Store(context.Background(), []*entities.Contact{{
+		ID:           uuid.New(),
+		UserID:       entities.UserID("user-1"),
+		Name:         "Alice",
+		Emails:       pq.StringArray{"alice@example.com"},
+		PhoneNumbers: pq.StringArray{"+18005550199"},
+	}})
+	assert.Nil(t, err)
+}
+```
+
+(The `messageThreadTestConnPool` and `messageThreadTestLogger` types are already defined in `gorm_message_thread_repository_test.go` in the same package, so they are reused directly here.)
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `cd api && go test -vet=off ./pkg/repositories/ -run TestGormContactRepository`
+Expected: FAIL / build error — `NewGormContactRepository` undefined.
+
+- [ ] **Step 4: Write the implementation**
+
+Create `api/pkg/repositories/gorm_contact_repository.go`:
+
+```go
+package repositories
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+// gormContactRepository is responsible for persisting entities.Contact
+type gormContactRepository struct {
+	logger telemetry.Logger
+	tracer telemetry.Tracer
+	db     *gorm.DB
+}
+
+// NewGormContactRepository creates the GORM version of the ContactRepository
+func NewGormContactRepository(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	db *gorm.DB,
+) ContactRepository {
+	return &gormContactRepository{
+		logger: logger.WithService(fmt.Sprintf("%T", &gormContactRepository{})),
+		tracer: tracer,
+		db:     db,
+	}
+}
+
+func (repository *gormContactRepository) Store(ctx context.Context, contacts []*entities.Contact) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if len(contacts) == 0 {
+		return nil
+	}
+
+	if err := repository.db.WithContext(ctx).Create(&contacts).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts", len(contacts)))
+	}
+	return nil
+}
+
+func (repository *gormContactRepository) Update(ctx context.Context, contact *entities.Contact) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if err := repository.db.WithContext(ctx).Save(contact).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact with ID [%s]", contact.ID))
+	}
+	return nil
+}
+
+func (repository *gormContactRepository) Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	contact := new(entities.Contact)
+	err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Where("id = ?", contactID).
+		First(contact).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, ErrCodeNotFound, "contact with id [%s] not found for user [%s]", contactID, userID))
+	}
+	if err != nil {
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot load contact with id [%s]", contactID))
+	}
+	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(
+			repository.db.Where("name ILIKE ?", queryPattern).
+				Or("array_to_string(emails, ',') ILIKE ?", queryPattern).
+				Or("array_to_string(phone_numbers, ',') ILIKE ?", queryPattern),
+		)
+	}
+
+	contacts := new([]entities.Contact)
+	if err := 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]", userID))
+	}
+	return contacts, nil
+}
+
+func (repository *gormContactRepository) FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error) {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	contacts := new([]entities.Contact)
+	if err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Order("updated_at ASC").
+		Find(contacts).Error; err != nil {
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch all contacts for user [%s]", userID))
+	}
+	return contacts, nil
+}
+
+func (repository *gormContactRepository) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Where("id = ?", contactID).
+		Delete(&entities.Contact{}).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact with id [%s] for user [%s]", contactID, userID))
+	}
+	return nil
+}
+
+func (repository *gormContactRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Delete(&entities.Contact{}).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete all contacts for user [%s]", userID))
+	}
+	return nil
+}
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `cd api && go test -vet=off ./pkg/repositories/ -run TestGormContactRepository`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add api/pkg/repositories/contact_repository.go api/pkg/repositories/gorm_contact_repository.go api/pkg/repositories/gorm_contact_repository_test.go
+git commit -m "feat(api): add ContactRepository with GORM implementation"
+```
+
+---
+
+### Task 4: Contact requests (store / update / index)
+
+**Files:**
+- Create: `api/pkg/requests/contact_store.go`
+- Create: `api/pkg/requests/contact_update.go`
+- Create: `api/pkg/requests/contact_index.go`
+- Create: `api/pkg/requests/contact_store_test.go`
+
+**Interfaces:**
+- Produces:
+  - `requests.ContactItem{ Name string; Emails []string; PhoneNumbers []string; Properties map[string]string }`
+  - `requests.ContactStoreRequest{ Contacts []ContactItem }` with `UnmarshalJSON` accepting a JSON array or `{"contacts":[...]}`; methods `Sanitize()` and `ToContacts(userID entities.UserID) []*entities.Contact`.
+  - `requests.ContactUpdateRequest{ Name string; Emails []string; PhoneNumbers []string; Properties map[string]string }` with `Sanitize()` and `ApplyTo(contact *entities.Contact)`.
+  - `requests.ContactIndex{ Skip, Query, Limit string }` with `Sanitize()` and `ToIndexParams() repositories.IndexParams`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `api/pkg/requests/contact_store_test.go`:
+
+```go
+package requests
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestContactStoreRequest_UnmarshalArrayForm(t *testing.T) {
+	var request ContactStoreRequest
+	require.NoError(t, json.Unmarshal([]byte(`[{"name":"Alice","phone_numbers":["+18005550199"]}]`), &request))
+	assert.Equal(t, 1, len(request.Contacts))
+	assert.Equal(t, "Alice", request.Contacts[0].Name)
+}
+
+func TestContactStoreRequest_UnmarshalObjectForm(t *testing.T) {
+	var request ContactStoreRequest
+	require.NoError(t, json.Unmarshal([]byte(`{"contacts":[{"name":"Bob","phone_numbers":["+18005550100"]}]}`), &request))
+	assert.Equal(t, 1, len(request.Contacts))
+	assert.Equal(t, "Bob", request.Contacts[0].Name)
+}
+
+func TestContactStoreRequest_SanitizeNormalizesNumbers(t *testing.T) {
+	request := ContactStoreRequest{Contacts: []ContactItem{{
+		Name:         "  Alice  ",
+		PhoneNumbers: []string{"18005550199"},
+		Emails:       []string{" alice@example.com "},
+	}}}
+	request = request.Sanitize()
+	assert.Equal(t, "Alice", request.Contacts[0].Name)
+	assert.Equal(t, "+18005550199", request.Contacts[0].PhoneNumbers[0])
+	assert.Equal(t, "alice@example.com", request.Contacts[0].Emails[0])
+}
+
+func TestContactStoreRequest_ToContacts(t *testing.T) {
+	request := ContactStoreRequest{Contacts: []ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+	}}}
+	contacts := request.ToContacts(entities.UserID("user-1"))
+	require.Equal(t, 1, len(contacts))
+	assert.Equal(t, "Alice", contacts[0].Name)
+	assert.Equal(t, entities.UserID("user-1"), contacts[0].UserID)
+	assert.NotEqual(t, "", contacts[0].ID.String())
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd api && go test -vet=off ./pkg/requests/ -run TestContactStoreRequest`
+Expected: FAIL / build error — types undefined.
+
+- [ ] **Step 3: Write the implementations**
+
+Create `api/pkg/requests/contact_store.go`:
+
+```go
+package requests
+
+import (
+	"encoding/json"
+	"strings"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+)
+
+// ContactItem is a single contact in a create request.
+type ContactItem struct {
+	Name         string            `json:"name" example:"Alice Smith"`
+	Emails       []string          `json:"emails"`
+	PhoneNumbers []string          `json:"phone_numbers"`
+	Properties   map[string]string `json:"properties"`
+}
+
+// ContactStoreRequest creates one or many contacts.
+type ContactStoreRequest struct {
+	request
+	Contacts []ContactItem `json:"contacts"`
+}
+
+// UnmarshalJSON accepts either a JSON array of contacts or {"contacts":[...]}.
+func (input *ContactStoreRequest) UnmarshalJSON(data []byte) error {
+	trimmed := strings.TrimSpace(string(data))
+	if strings.HasPrefix(trimmed, "[") {
+		var items []ContactItem
+		if err := json.Unmarshal(data, &items); err != nil {
+			return err
+		}
+		input.Contacts = items
+		return nil
+	}
+
+	type alias ContactStoreRequest
+	var wrapper alias
+	if err := json.Unmarshal(data, &wrapper); err != nil {
+		return err
+	}
+	input.Contacts = wrapper.Contacts
+	return nil
+}
+
+// Sanitize trims and normalizes each contact item.
+func (input ContactStoreRequest) Sanitize() ContactStoreRequest {
+	for index := range input.Contacts {
+		input.Contacts[index] = input.sanitizeItem(input.Contacts[index])
+	}
+	return input
+}
+
+func (input *ContactStoreRequest) sanitizeItem(item ContactItem) ContactItem {
+	item.Name = strings.TrimSpace(item.Name)
+
+	numbers := input.removeStringDuplicates(input.removeEmptyStrings(item.PhoneNumbers))
+	item.PhoneNumbers = input.sanitizeAddresses(numbers)
+
+	emails := input.removeEmptyStrings(item.Emails)
+	for i := range emails {
+		emails[i] = strings.ToLower(strings.TrimSpace(emails[i]))
+	}
+	item.Emails = input.removeStringDuplicates(emails)
+
+	if item.Properties == nil {
+		item.Properties = map[string]string{}
+	}
+	return item
+}
+
+// ToContacts converts the request into persistable entities.Contact records.
+func (input *ContactStoreRequest) ToContacts(userID entities.UserID) []*entities.Contact {
+	now := time.Now().UTC()
+	contacts := make([]*entities.Contact, 0, len(input.Contacts))
+	for _, item := range input.Contacts {
+		contacts = append(contacts, &entities.Contact{
+			ID:           uuid.New(),
+			UserID:       userID,
+			Name:         item.Name,
+			Emails:       pq.StringArray(item.Emails),
+			PhoneNumbers: pq.StringArray(item.PhoneNumbers),
+			Properties:   entities.ContactProperties(item.Properties),
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		})
+	}
+	return contacts
+}
+```
+
+Create `api/pkg/requests/contact_update.go`:
+
+```go
+package requests
+
+import (
+	"strings"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/lib/pq"
+)
+
+// ContactUpdateRequest updates an existing contact.
+type ContactUpdateRequest struct {
+	request
+	Name         string            `json:"name" example:"Alice Smith"`
+	Emails       []string          `json:"emails"`
+	PhoneNumbers []string          `json:"phone_numbers"`
+	Properties   map[string]string `json:"properties"`
+}
+
+// Sanitize trims and normalizes the update request.
+func (input ContactUpdateRequest) Sanitize() ContactUpdateRequest {
+	input.Name = strings.TrimSpace(input.Name)
+
+	numbers := input.removeStringDuplicates(input.removeEmptyStrings(input.PhoneNumbers))
+	input.PhoneNumbers = input.sanitizeAddresses(numbers)
+
+	emails := input.removeEmptyStrings(input.Emails)
+	for i := range emails {
+		emails[i] = strings.ToLower(strings.TrimSpace(emails[i]))
+	}
+	input.Emails = input.removeStringDuplicates(emails)
+
+	if input.Properties == nil {
+		input.Properties = map[string]string{}
+	}
+	return input
+}
+
+// ApplyTo mutates an existing contact with the update values.
+func (input *ContactUpdateRequest) ApplyTo(contact *entities.Contact) {
+	contact.Name = input.Name
+	contact.Emails = pq.StringArray(input.Emails)
+	contact.PhoneNumbers = pq.StringArray(input.PhoneNumbers)
+	contact.Properties = entities.ContactProperties(input.Properties)
+	contact.UpdatedAt = time.Now().UTC()
+}
+```
+
+Create `api/pkg/requests/contact_index.go`:
+
+```go
+package requests
+
+import (
+	"strings"
+
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+)
+
+// ContactIndex lists contacts for a user.
+type ContactIndex struct {
+	request
+	Skip  string `json:"skip" query:"skip"`
+	Query string `json:"query" query:"query"`
+	Limit string `json:"limit" query:"limit"`
+}
+
+// Sanitize sets defaults for the list request.
+func (input *ContactIndex) Sanitize() ContactIndex {
+	if strings.TrimSpace(input.Limit) == "" {
+		input.Limit = "20"
+	}
+	input.Query = strings.TrimSpace(input.Query)
+	input.Skip = strings.TrimSpace(input.Skip)
+	if input.Skip == "" {
+		input.Skip = "0"
+	}
+	return *input
+}
+
+// ToIndexParams converts the request into repositories.IndexParams.
+func (input *ContactIndex) ToIndexParams() repositories.IndexParams {
+	return repositories.IndexParams{
+		Skip:  input.getInt(input.Skip),
+		Query: input.Query,
+		Limit: input.getInt(input.Limit),
+	}
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd api && go test -vet=off ./pkg/requests/ -run TestContactStoreRequest`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add api/pkg/requests/contact_store.go api/pkg/requests/contact_update.go api/pkg/requests/contact_index.go api/pkg/requests/contact_store_test.go
+git commit -m "feat(api): add contact store/update/index requests"
+```
+
+---
+
+### Task 5: ContactHandlerValidator (store / update / index / CSV upload)
+
+**Files:**
+- Create: `api/pkg/validators/contact_handler_validator.go`
+- Create: `api/pkg/validators/contact_handler_validator_test.go`
+
+**Interfaces:**
+- Consumes: `requests.ContactStoreRequest`, `requests.ContactUpdateRequest`, `requests.ContactIndex`, `requests.ContactItem`.
+- Produces: `validators.ContactHandlerValidator` with:
+  - `NewContactHandlerValidator(logger, tracer) *ContactHandlerValidator`
+  - `ValidateStore(ctx, request requests.ContactStoreRequest) url.Values`
+  - `ValidateUpdate(ctx, request requests.ContactUpdateRequest) url.Values`
+  - `ValidateIndex(ctx, request requests.ContactIndex) url.Values`
+  - `ValidateUpload(ctx, userID entities.UserID, header *multipart.FileHeader) ([]requests.ContactItem, url.Values)`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `api/pkg/validators/contact_handler_validator_test.go`:
+
+```go
+package validators
+
+import (
+	"context"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/requests"
+	"github.com/stretchr/testify/assert"
+)
+
+func newContactValidator() *ContactHandlerValidator {
+	return &ContactHandlerValidator{}
+}
+
+func TestContactValidator_ValidateStore_Valid(t *testing.T) {
+	v := newContactValidator()
+	errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+		Emails:       []string{"alice@example.com"},
+	}}})
+	assert.Equal(t, 0, len(errs))
+}
+
+func TestContactValidator_ValidateStore_MissingName(t *testing.T) {
+	v := newContactValidator()
+	errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		PhoneNumbers: []string{"+18005550199"},
+	}}})
+	assert.NotEqual(t, 0, len(errs))
+}
+
+func TestContactValidator_ValidateStore_InvalidNumber(t *testing.T) {
+	v := newContactValidator()
+	errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"not-a-number"},
+	}}})
+	assert.NotEqual(t, 0, len(errs))
+}
+
+func TestContactValidator_ValidateStore_EmptyBatch(t *testing.T) {
+	v := newContactValidator()
+	errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: nil})
+	assert.NotEqual(t, 0, len(errs))
+}
+
+func TestContactValidator_ValidateStore_InvalidEmail(t *testing.T) {
+	v := newContactValidator()
+	errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+		Emails:       []string{"not-an-email"},
+	}}})
+	assert.NotEqual(t, 0, len(errs))
+}
+```
+
+(If `telemetry.NewOtelLogger` for the tracer differs in your package, `ValidateUpload` is the only method needing a real logger/tracer; the store/update/index tests use a zero-value validator.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd api && go test -vet=off ./pkg/validators/ -run TestContactValidator`
+Expected: FAIL / build error — `NewContactHandlerValidator` undefined.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `api/pkg/validators/contact_handler_validator.go`:
+
+```go
+package validators
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/mail"
+	"net/url"
+	"strings"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/requests"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/jszwec/csvutil"
+	"github.com/nyaruka/phonenumbers"
+	"github.com/thedevsaddam/govalidator"
+)
+
+// ContactHandlerValidator validates models used in handlers.ContactHandler
+type ContactHandlerValidator struct {
+	validator
+	logger telemetry.Logger
+	tracer telemetry.Tracer
+}
+
+// NewContactHandlerValidator creates a new handlers.ContactHandler validator
+func NewContactHandlerValidator(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+) *ContactHandlerValidator {
+	return &ContactHandlerValidator{
+		logger: logger.WithService(fmt.Sprintf("%T", &ContactHandlerValidator{})),
+		tracer: tracer,
+	}
+}
+
+const maxContactBatch = 1000
+
+// ValidateStore validates a create request of one or many contacts.
+func (v *ContactHandlerValidator) ValidateStore(_ context.Context, request requests.ContactStoreRequest) url.Values {
+	result := url.Values{}
+	if len(request.Contacts) == 0 {
+		result.Add("contacts", "You must provide at least one contact.")
+		return result
+	}
+	if len(request.Contacts) > maxContactBatch {
+		result.Add("contacts", fmt.Sprintf("You cannot create more than %d contacts in one request.", maxContactBatch))
+		return result
+	}
+	for index, item := range request.Contacts {
+		v.validateItem(result, index, item)
+	}
+	return result
+}
+
+// ValidateUpdate validates a single contact update.
+func (v *ContactHandlerValidator) ValidateUpdate(_ context.Context, request requests.ContactUpdateRequest) url.Values {
+	result := url.Values{}
+	v.validateItem(result, 0, requests.ContactItem{
+		Name:         request.Name,
+		Emails:       request.Emails,
+		PhoneNumbers: request.PhoneNumbers,
+		Properties:   request.Properties,
+	})
+	return result
+}
+
+func (v *ContactHandlerValidator) validateItem(result url.Values, index int, item requests.ContactItem) {
+	row := index + 1
+	if strings.TrimSpace(item.Name) == "" {
+		result.Add("contacts", fmt.Sprintf("Contact [%d]: The name is required.", row))
+	}
+	if len(item.PhoneNumbers) == 0 {
+		result.Add("contacts", fmt.Sprintf("Contact [%d]: At least one phone number is required.", row))
+	}
+	for _, number := range item.PhoneNumbers {
+		if _, err := phonenumbers.Parse(number, phonenumbers.UNKNOWN_REGION); err != nil {
+			result.Add("contacts", fmt.Sprintf("Contact [%d]: The phone number [%s] is not a valid E.164 phone number.", row, number))
+		}
+	}
+	for _, email := range item.Emails {
+		if _, err := mail.ParseAddress(email); err != nil {
+			result.Add("contacts", fmt.Sprintf("Contact [%d]: The email [%s] is not a valid email address.", row, email))
+		}
+	}
+}
+
+// ValidateIndex validates the list request.
+func (v *ContactHandlerValidator) ValidateIndex(_ context.Context, request requests.ContactIndex) url.Values {
+	value := govalidator.New(govalidator.Options{
+		Data: &request,
+		Rules: govalidator.MapData{
+			"limit": []string{"required", "numeric", "min:1", "max:100"},
+			"skip":  []string{"required", "numeric", "min:0"},
+			"query": []string{"max:100"},
+		},
+	})
+	return value.ValidateStruct()
+}
+
+type contactCSVRow struct {
+	Name         string `csv:"Name"`
+	Emails       string `csv:"Emails"`
+	PhoneNumbers string `csv:"PhoneNumbers"`
+}
+
+// ValidateUpload parses and validates a CSV upload (CSV only).
+func (v *ContactHandlerValidator) ValidateUpload(ctx context.Context, userID entities.UserID, header *multipart.FileHeader) ([]requests.ContactItem, url.Values) {
+	ctx, span, ctxLogger := v.tracer.StartWithLogger(ctx, v.logger)
+	defer span.End()
+	_ = ctx
+
+	result := url.Values{}
+
+	if header.Header.Get("Content-Type") != "text/csv" && !strings.HasSuffix(strings.ToLower(header.Filename), ".csv") {
+		result.Add("document", fmt.Sprintf("The file [%s] is not a valid CSV file. Only CSV files are supported.", header.Filename))
+		return nil, result
+	}
+
+	if header.Size >= 500000 {
+		result.Add("document", "The CSV file must be less than 500 KB.")
+		return nil, result
+	}
+
+	file, err := header.Open()
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot open file [%s] for user [%s]", header.Filename, userID))
+		result.Add("document", fmt.Sprintf("Cannot open the uploaded file [%s].", header.Filename))
+		return nil, result
+	}
+	defer func() { _ = file.Close() }()
+
+	buffer := new(bytes.Buffer)
+	if _, err = io.Copy(buffer, file); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot read file [%s] for user [%s]", header.Filename, userID))
+		result.Add("document", fmt.Sprintf("Cannot read the uploaded file [%s].", header.Filename))
+		return nil, result
+	}
+
+	var rows []contactCSVRow
+	if err = csvutil.Unmarshal(buffer.Bytes(), &rows); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot parse CSV file [%s] for user [%s]", header.Filename, userID))
+		result.Add("document", fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. Use the official httpSMS contacts template.", header.Filename))
+		return nil, result
+	}
+
+	if len(rows) > maxContactBatch {
+		result.Add("document", fmt.Sprintf("The uploaded file must contain less than %d records.", maxContactBatch))
+		return nil, result
+	}
+
+	items := make([]requests.ContactItem, 0, len(rows))
+	for _, row := range rows {
+		if strings.TrimSpace(row.Name) == "" && strings.TrimSpace(row.PhoneNumbers) == "" {
+			continue
+		}
+		items = append(items, requests.ContactItem{
+			Name:         strings.TrimSpace(row.Name),
+			Emails:       splitMultiValue(row.Emails),
+			PhoneNumbers: splitMultiValue(row.PhoneNumbers),
+		})
+	}
+
+	if len(items) == 0 {
+		result.Add("document", "The uploaded file doesn't contain any valid records.")
+	}
+	return items, result
+}
+
+func splitMultiValue(value string) []string {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+	fields := strings.FieldsFunc(value, func(r rune) bool { return r == ';' || r == ',' })
+	var result []string
+	for _, field := range fields {
+		field = strings.TrimSpace(field)
+		if field != "" {
+			result = append(result, field)
+		}
+	}
+	return result
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd api && go test -vet=off ./pkg/validators/ -run TestContactValidator`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add api/pkg/validators/contact_handler_validator.go api/pkg/validators/contact_handler_validator_test.go
+git commit -m "feat(api): add ContactHandlerValidator with CSV-only upload parsing"
+```
+
+---
+
+### Task 6: ContactService (CRUD + contact-map cache + invalidation)
+
+**Files:**
+- Create: `api/pkg/services/contact_service.go`
+- Create: `api/pkg/services/contact_service_test.go`
+
+**Interfaces:**
+- Consumes: `repositories.ContactRepository`, `cache.Cache`, `entities.Contact`, `repositories.IndexParams`.
+- Produces: `services.ContactService` with:
+  - `NewContactService(logger, tracer, repository repositories.ContactRepository, appCache cache.Cache) *ContactService`
+  - `CreateMany(ctx, userID entities.UserID, contacts []*entities.Contact) error`
+  - `Get(ctx, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)`
+  - `Index(ctx, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error)`
+  - `Update(ctx, contact *entities.Contact) error`
+  - `Delete(ctx, userID entities.UserID, contactID uuid.UUID) error`
+  - `GetContactMap(ctx, userID entities.UserID) (map[string]*entities.Contact, error)` (cache-backed; most-recently-updated wins)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `api/pkg/services/contact_service_test.go`:
+
+```go
+package services
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type fakeCache struct {
+	store map[string]string
+}
+
+func newFakeCache() *fakeCache { return &fakeCache{store: map[string]string{}} }
+
+func (c *fakeCache) Get(_ context.Context, key string) (string, error) {
+	value, ok := c.store[key]
+	if !ok {
+		return "", assertMiss{}
+	}
+	return value, nil
+}
+
+func (c *fakeCache) Set(_ context.Context, key, value string, _ time.Duration) error {
+	c.store[key] = value
+	return nil
+}
+
+type assertMiss struct{}
+
+func (assertMiss) Error() string { return "miss" }
+
+type fakeContactRepo struct {
+	contacts  []*entities.Contact
+	fetchAll  int
+}
+
+func (r *fakeContactRepo) Store(_ context.Context, contacts []*entities.Contact) error {
+	r.contacts = append(r.contacts, contacts...)
+	return nil
+}
+func (r *fakeContactRepo) Update(_ context.Context, contact *entities.Contact) error { return nil }
+func (r *fakeContactRepo) Load(_ context.Context, _ entities.UserID, id uuid.UUID) (*entities.Contact, error) {
+	for _, c := range r.contacts {
+		if c.ID == id {
+			return c, nil
+		}
+	}
+	return nil, stacktrace.NewErrorWithCodef(repositories.ErrCodeNotFound, "contact [%s] not found", id)
+}
+func (r *fakeContactRepo) Index(_ context.Context, _ entities.UserID, _ repositories.IndexParams) (*[]entities.Contact, error) {
+	out := []entities.Contact{}
+	return &out, nil
+}
+func (r *fakeContactRepo) FetchAll(_ context.Context, _ entities.UserID) (*[]entities.Contact, error) {
+	r.fetchAll++
+	out := make([]entities.Contact, 0, len(r.contacts))
+	for _, c := range r.contacts {
+		out = append(out, *c)
+	}
+	return &out, nil
+}
+func (r *fakeContactRepo) Delete(_ context.Context, _ entities.UserID, _ uuid.UUID) error { return nil }
+func (r *fakeContactRepo) DeleteAllForUser(_ context.Context, _ entities.UserID) error   { return nil }
+
+func newContactService(repo repositories.ContactRepository, appCache *fakeCache) *ContactService {
+	logger := telemetry.NewZerologLogger("test", nil, nil, nil)
+	return NewContactService(logger, telemetry.NewOtelLogger("test", logger), repo, appCache)
+}
+
+func TestContactService_GetContactMap_TieBreakMostRecentlyUpdated(t *testing.T) {
+	older := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Old", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now().Add(-time.Hour)}
+	newer := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "New", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now()}
+	// FetchAll returns ASC by updated_at, so older first then newer.
+	repo := &fakeContactRepo{contacts: []*entities.Contact{older, newer}}
+	service := newContactService(repo, newFakeCache())
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	require.NotNil(t, result["+18005550199"])
+	assert.Equal(t, "New", result["+18005550199"].Name)
+}
+
+func TestContactService_GetContactMap_UsesCacheOnSecondCall(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}}
+	service := newContactService(repo, newFakeCache())
+
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	_, err = service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, repo.fetchAll)
+}
+
+func TestContactService_CreateMany_InvalidatesCache(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}}
+	appCache := newFakeCache()
+	service := newContactService(repo, appCache)
+
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	require.Equal(t, 1, repo.fetchAll)
+
+	require.NoError(t, service.CreateMany(context.Background(), entities.UserID("u1"), []*entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}}}))
+
+	_, err = service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	assert.Equal(t, 2, repo.fetchAll)
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd api && go test -vet=off ./pkg/services/ -run TestContactService`
+Expected: FAIL / build error — `NewContactService` undefined.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `api/pkg/services/contact_service.go`:
+
+```go
+package services
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/cache"
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+)
+
+const contactMapCacheTTL = 24 * time.Hour
+
+// ContactService handles contact business logic.
+type ContactService struct {
+	service
+	logger     telemetry.Logger
+	tracer     telemetry.Tracer
+	repository repositories.ContactRepository
+	cache      cache.Cache
+}
+
+// NewContactService creates a new ContactService.
+func NewContactService(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	repository repositories.ContactRepository,
+	appCache cache.Cache,
+) (s *ContactService) {
+	return &ContactService{
+		logger:     logger.WithService(fmt.Sprintf("%T", s)),
+		tracer:     tracer,
+		repository: repository,
+		cache:      appCache,
+	}
+}
+
+func (service *ContactService) cacheKey(userID entities.UserID) string {
+	return fmt.Sprintf("contacts.map.%s", userID)
+}
+
+// CreateMany persists one or many contacts then invalidates the cache.
+func (service *ContactService) CreateMany(ctx context.Context, userID entities.UserID, contacts []*entities.Contact) error {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	if err := service.repository.Store(ctx, contacts); err != nil {
+		return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts for user [%s]", len(contacts), userID))
+	}
+	service.invalidate(ctx, userID)
+	return nil
+}
+
+// Get returns a contact by ID.
+func (service *ContactService) Get(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	contact, err := service.repository.Load(ctx, userID, contactID)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, stacktrace.GetCode(err), "cannot load contact [%s] for user [%s]", contactID, userID))
+	}
+	return contact, nil
+}
+
+// Index lists contacts for a user.
+func (service *ContactService) Index(ctx context.Context, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	contacts, err := service.repository.Index(ctx, userID, params)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s]", userID))
+	}
+	return contacts, nil
+}
+
+// Update saves a contact and invalidates the cache.
+func (service *ContactService) Update(ctx context.Context, contact *entities.Contact) error {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	if err := service.repository.Update(ctx, contact); err != nil {
+		return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact [%s]", contact.ID))
+	}
+	service.invalidate(ctx, contact.UserID)
+	return nil
+}
+
+// Delete removes a contact and invalidates the cache.
+func (service *ContactService) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	if err := service.repository.Delete(ctx, userID, contactID); err != nil {
+		return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))
+	}
+	service.invalidate(ctx, userID)
+	return nil
+}
+
+// GetContactMap returns the cached phone_number -> *Contact map for a user.
+func (service *ContactService) GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	if raw, err := service.cache.Get(ctx, service.cacheKey(userID)); err == nil && raw != "" {
+		result := map[string]*entities.Contact{}
+		if jsonErr := json.Unmarshal([]byte(raw), &result); jsonErr == nil {
+			return result, nil
+		}
+	}
+
+	contacts, err := service.repository.FetchAll(ctx, userID)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts to build map for user [%s]", userID))
+	}
+
+	// FetchAll returns updated_at ASC, so later (more recently updated) contacts overwrite earlier ones.
+	result := map[string]*entities.Contact{}
+	for index := range *contacts {
+		contact := (*contacts)[index]
+		for _, number := range contact.PhoneNumbers {
+			copied := contact
+			result[number] = &copied
+		}
+	}
+
+	if encoded, encodeErr := json.Marshal(result); encodeErr == nil {
+		_ = service.cache.Set(ctx, service.cacheKey(userID), string(encoded), contactMapCacheTTL)
+	}
+
+	return result, nil
+}
+
+// invalidate overwrites the cache key with an empty marker (Cache has no Delete).
+func (service *ContactService) invalidate(ctx context.Context, userID entities.UserID) {
+	if err := service.cache.Set(ctx, service.cacheKey(userID), "", contactMapCacheTTL); err != nil {
+		service.logger.Error(stacktrace.Propagatef(err, "cannot invalidate contact map cache for user [%s]", userID))
+	}
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd api && go test -vet=off ./pkg/services/ -run TestContactService`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add api/pkg/services/contact_service.go api/pkg/services/contact_service_test.go
+git commit -m "feat(api): add ContactService with cached contact-map resolution"
+```
+
+---
+
+### Task 7: Opt-in contact resolution in GetThreads
+
+**Files:**
+- Modify: `api/pkg/services/message_thread_service.go` (struct, constructor, `MessageThreadGetParams`, `GetThreads`)
+- Modify: `api/pkg/requests/message_thread_index_request.go` (`Contacts` param + `ToGetParams`)
+- Modify: `api/pkg/handlers/message_thread_handler_test.go` (add 6th constructor arg)
+- Create: `api/pkg/services/message_thread_service_contacts_test.go`
+- Create: `api/pkg/requests/message_thread_index_request_test.go`
+
+**Interfaces:**
+- Consumes: `ContactService.GetContactMap(ctx, userID) (map[string]*entities.Contact, error)` (Task 6); `entities.MessageThread.ContactDetails` (Task 2).
+- Produces: `MessageThreadGetParams.WithContacts bool`; `MessageThreadService` gains a `contactService contactMapProvider` field where `contactMapProvider` is:
+  ```go
+  type contactMapProvider interface {
+      GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error)
+  }
+  ```
+  `*ContactService` satisfies `contactMapProvider`. New constructor signature:
+  `NewMessageThreadService(logger, tracer, repository, phoneRepository, eventDispatcher, contactService contactMapProvider) *MessageThreadService`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `api/pkg/requests/message_thread_index_request_test.go`:
+
+```go
+package requests
+
+import (
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMessageThreadIndex_ToGetParams_WithContacts(t *testing.T) {
+	input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: "true"}).Sanitize()
+	params := input.ToGetParams(entities.UserID("u1"))
+	assert.True(t, params.WithContacts)
+}
+
+func TestMessageThreadIndex_ToGetParams_WithoutContacts(t *testing.T) {
+	input := (&MessageThreadIndex{Owner: "+18005550199"}).Sanitize()
+	params := input.ToGetParams(entities.UserID("u1"))
+	assert.False(t, params.WithContacts)
+}
+```
+
+Create `api/pkg/services/message_thread_service_contacts_test.go`:
+
+```go
+package services
+
+import (
+	"context"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type stubThreadRepo struct {
+	repositories.MessageThreadRepository
+	threads []entities.MessageThread
+}
+
+func (r *stubThreadRepo) Index(_ context.Context, _ entities.UserID, _ string, _ bool, _ repositories.IndexParams) (*[]entities.MessageThread, error) {
+	out := make([]entities.MessageThread, len(r.threads))
+	copy(out, r.threads)
+	return &out, nil
+}
+
+type stubContactProvider struct {
+	contactMap map[string]*entities.Contact
+	calls      int
+}
+
+func (p *stubContactProvider) GetContactMap(_ context.Context, _ entities.UserID) (map[string]*entities.Contact, error) {
+	p.calls++
+	return p.contactMap, nil
+}
+
+func newThreadServiceWithContacts(repo repositories.MessageThreadRepository, provider contactMapProvider) *MessageThreadService {
+	logger := telemetry.NewZerologLogger("test", nil, nil, nil)
+	return NewMessageThreadService(logger, telemetry.NewOtelLogger("test", logger), repo, nil, nil, provider)
+}
+
+func TestGetThreads_AttachesContactDetailsWhenWithContacts(t *testing.T) {
+	repo := &stubThreadRepo{threads: []entities.MessageThread{{Contact: "+18005550199"}, {Contact: "+18005550100"}}}
+	provider := &stubContactProvider{contactMap: map[string]*entities.Contact{"+18005550199": {Name: "Alice"}}}
+	service := newThreadServiceWithContacts(repo, provider)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: "u1", WithContacts: true})
+	require.NoError(t, err)
+	require.Len(t, *threads, 2)
+	require.NotNil(t, (*threads)[0].ContactDetails)
+	assert.Equal(t, "Alice", (*threads)[0].ContactDetails.Name)
+	assert.Nil(t, (*threads)[1].ContactDetails)
+}
+
+func TestGetThreads_SkipsContactLookupWhenFlagOff(t *testing.T) {
+	repo := &stubThreadRepo{threads: []entities.MessageThread{{Contact: "+18005550199"}}}
+	provider := &stubContactProvider{contactMap: map[string]*entities.Contact{"+18005550199": {Name: "Alice"}}}
+	service := newThreadServiceWithContacts(repo, provider)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: "u1", WithContacts: false})
+	require.NoError(t, err)
+	assert.Nil(t, (*threads)[0].ContactDetails)
+	assert.Equal(t, 0, provider.calls)
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd api && go test -vet=off ./pkg/requests/ -run TestMessageThreadIndex_ToGetParams && go test -vet=off ./pkg/services/ -run TestGetThreads`
+Expected: FAIL / build error — `Contacts`, `WithContacts`, and the 6-arg constructor do not exist yet.
+
+- [ ] **Step 3: Implement request changes**
+
+In `api/pkg/requests/message_thread_index_request.go`, add the field to the struct:
+
+```go
+	Owner      string `json:"owner" query:"owner"`
+	Contacts   string `json:"contacts" query:"contacts" example:"true"`
+```
+
+Add sanitisation inside `Sanitize()` (before `return *input`):
+
+```go
+	input.Contacts = input.sanitizeBool(input.Contacts)
+```
+
+Add the field to the returned params in `ToGetParams`:
+
+```go
+		UserID:       userID,
+		IsArchived:   input.getBool(input.IsArchived),
+		Owner:        input.Owner,
+		WithContacts: input.getBool(input.Contacts),
+	}
+```
+
+- [ ] **Step 4: Implement service changes**
+
+In `api/pkg/services/message_thread_service.go` add the provider interface (top-level, after imports):
+
+```go
+// contactMapProvider supplies the phone_number -> *Contact map for a user.
+type contactMapProvider interface {
+	GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error)
+}
+```
+
+Add the field to the struct:
+
+```go
+	eventDispatcher *EventDispatcher
+	contactService  contactMapProvider
+```
+
+Update the constructor:
+
+```go
+func NewMessageThreadService(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	repository repositories.MessageThreadRepository,
+	phoneRepository repositories.PhoneRepository,
+	eventDispatcher *EventDispatcher,
+	contactService contactMapProvider,
+) (s *MessageThreadService) {
+	return &MessageThreadService{
+		logger:          logger.WithService(fmt.Sprintf("%T", s)),
+		tracer:          tracer,
+		eventDispatcher: eventDispatcher,
+		repository:      repository,
+		phoneRepository: phoneRepository,
+		contactService:  contactService,
+	}
+}
+```
+
+Add `WithContacts` to the params struct:
+
+```go
+type MessageThreadGetParams struct {
+	repositories.IndexParams
+	IsArchived   bool
+	WithContacts bool
+	UserID       entities.UserID
+	Owner        string
+}
+```
+
+Extend `GetThreads` to attach contact details (replace its body):
+
+```go
+func (service *MessageThreadService) GetThreads(ctx context.Context, params MessageThreadGetParams) (*[]entities.MessageThread, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	ctxLogger := service.tracer.CtxLogger(service.logger, span)
+
+	threads, err := service.repository.Index(ctx, params.UserID, params.Owner, params.IsArchived, params.IndexParams)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "could not fetch messages threads for params [%+#v]", params))
+	}
+
+	if params.WithContacts && service.contactService != nil && len(*threads) > 0 {
+		contactMap, mapErr := service.contactService.GetContactMap(ctx, params.UserID)
+		if mapErr != nil {
+			ctxLogger.Error(service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(mapErr, "cannot build contact map for user [%s]", params.UserID)))
+		} else {
+			for index := range *threads {
+				if contact, ok := contactMap[(*threads)[index].Contact]; ok {
+					(*threads)[index].ContactDetails = contact
+				}
+			}
+		}
+	}
+
+	ctxLogger.Info(fmt.Sprintf("fetched [%d] threads with params [%+#v]", len(*threads), params))
+	return threads, nil
+}
+```
+
+- [ ] **Step 5: Update DI wiring and existing callers**
+
+In `api/pkg/di/container.go`, find `NewMessageThreadService(...)` and append `container.ContactService()` as the final argument (the `ContactService()` getter is added in Task 8; if wiring Task 8 first, this compiles immediately — otherwise temporarily pass `nil` and restore in Task 8).
+
+Also update the existing test `api/pkg/handlers/message_thread_handler_test.go`: its call `services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil)` now needs a sixth argument — change it to `services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil, nil)`.
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `cd api && go test -vet=off ./pkg/requests/ -run TestMessageThreadIndex_ToGetParams && go test -vet=off ./pkg/services/ -run TestGetThreads`
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add api/pkg/services/message_thread_service.go api/pkg/services/message_thread_service_contacts_test.go api/pkg/requests/message_thread_index_request.go api/pkg/requests/message_thread_index_request_test.go api/pkg/handlers/message_thread_handler_test.go api/pkg/di/container.go
+git commit -m "feat(api): opt-in contact resolution for message threads via ?contacts=true"
+```
+
+---
+
+### Task 8: ContactHandler + DI wiring + route registration
+
+**Files:**
+- Create: `api/pkg/handlers/contact_handler.go`
+- Create: `api/pkg/handlers/contact_handler_test.go`
+- Modify: `api/pkg/di/container.go` (getters, AutoMigrate, RegisterContactRoutes, wire ContactService into MessageThreadService)
+
+**Interfaces:**
+- Consumes: `services.ContactService` (Task 6), `validators.ContactHandlerValidator` (Task 5), `requests.*` (Task 4), `repositories.ErrCodeNotFound`.
+- Produces: `handlers.ContactHandler` with `NewContactHandler(logger, tracer, validator *validators.ContactHandlerValidator, service *services.ContactService) *ContactHandler` and `RegisterRoutes(router, ...middlewares)`. Routes: `GET /v1/contacts`, `POST /v1/contacts`, `POST /v1/contacts/upload`, `PUT /v1/contacts/:contactID`, `DELETE /v1/contacts/:contactID`. New DI getters: `container.ContactRepository()`, `container.ContactService()`, `container.ContactHandlerValidator()`, `container.ContactHandler()`, `container.RegisterContactRoutes()`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `api/pkg/handlers/contact_handler_test.go`:
+
+```go
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/cache"
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/middlewares"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/services"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/httpsms/pkg/validators"
+	"github.com/gofiber/fiber/v3"
+	"github.com/google/uuid"
+	ttlCache "github.com/patrickmn/go-cache"
+	"github.com/stretchr/testify/require"
+)
+
+type contactHandlerRepoStub struct {
+	stored []*entities.Contact
+}
+
+func (s *contactHandlerRepoStub) Store(_ context.Context, contacts []*entities.Contact) error {
+	s.stored = append(s.stored, contacts...)
+	return nil
+}
+func (s *contactHandlerRepoStub) Update(context.Context, *entities.Contact) error { return nil }
+func (s *contactHandlerRepoStub) Load(context.Context, entities.UserID, uuid.UUID) (*entities.Contact, error) {
+	return nil, nil
+}
+func (s *contactHandlerRepoStub) Index(context.Context, entities.UserID, repositories.IndexParams) (*[]entities.Contact, error) {
+	out := []entities.Contact{}
+	return &out, nil
+}
+func (s *contactHandlerRepoStub) FetchAll(context.Context, entities.UserID) (*[]entities.Contact, error) {
+	out := []entities.Contact{}
+	return &out, nil
+}
+func (s *contactHandlerRepoStub) Delete(context.Context, entities.UserID, uuid.UUID) error { return nil }
+func (s *contactHandlerRepoStub) DeleteAllForUser(context.Context, entities.UserID) error  { return nil }
+
+func newContactTestApp(repo repositories.ContactRepository) *fiber.App {
+	logger := &messageThreadHandlerNoopLogger{}
+	tracer := telemetry.NewOtelLogger("test", logger)
+	appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))
+	service := services.NewContactService(logger, tracer, repo, appCache)
+	handler := NewContactHandler(logger, tracer, &validators.ContactHandlerValidator{}, service)
+
+	app := fiber.New()
+	app.Use(func(c fiber.Ctx) error {
+		c.Locals(middlewares.ContextKeyAuthUserID, entities.AuthContext{ID: entities.UserID("user-id"), Email: "user@example.com"})
+		return c.Next()
+	})
+	handler.RegisterRoutes(app)
+	return app
+}
+
+func TestContactHandler_Store_CreatesContacts(t *testing.T) {
+	repo := &contactHandlerRepoStub{}
+	app := newContactTestApp(repo)
+
+	body := `[{"name":"Alice","phone_numbers":["+18005550199"]}]`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusCreated, resp.StatusCode)
+	require.Len(t, repo.stored, 1)
+	require.Equal(t, "Alice", repo.stored[0].Name)
+}
+
+func TestContactHandler_Store_ValidationError(t *testing.T) {
+	app := newContactTestApp(&contactHandlerRepoStub{})
+
+	body := `[{"name":"","phone_numbers":[]}]`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+}
+
+func TestContactHandler_Index_ReturnsOK(t *testing.T) {
+	app := newContactTestApp(&contactHandlerRepoStub{})
+
+	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.StatusOK, resp.StatusCode)
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd api && go test -vet=off ./pkg/handlers/ -run TestContactHandler`
+Expected: FAIL / build error — `NewContactHandler` undefined.
+
+- [ ] **Step 3: Write the handler**
+
+Create `api/pkg/handlers/contact_handler.go`:
+
+```go
+package handlers
+
+import (
+	"fmt"
+
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/requests"
+	"github.com/NdoleStudio/httpsms/pkg/services"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/httpsms/pkg/validators"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/davecgh/go-spew/spew"
+	"github.com/gofiber/fiber/v3"
+	"github.com/google/uuid"
+)
+
+// ContactHandler handles contact http requests.
+type ContactHandler struct {
+	handler
+	logger    telemetry.Logger
+	tracer    telemetry.Tracer
+	validator *validators.ContactHandlerValidator
+	service   *services.ContactService
+}
+
+// NewContactHandler creates a new ContactHandler.
+func NewContactHandler(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	validator *validators.ContactHandlerValidator,
+	service *services.ContactService,
+) (h *ContactHandler) {
+	return &ContactHandler{
+		logger:    logger.WithService(fmt.Sprintf("%T", h)),
+		tracer:    tracer,
+		validator: validator,
+		service:   service,
+	}
+}
+
+// RegisterRoutes registers the routes for the ContactHandler.
+func (h *ContactHandler) RegisterRoutes(router fiber.Router, middlewares ...fiber.Handler) {
+	h.register(router, fiber.MethodGet, "/v1/contacts", middlewares, h.Index)
+	h.register(router, fiber.MethodPost, "/v1/contacts", middlewares, h.Store)
+	h.register(router, fiber.MethodPost, "/v1/contacts/upload", middlewares, h.Upload)
+	h.register(router, fiber.MethodPut, "/v1/contacts/:contactID", middlewares, h.Update)
+	h.register(router, fiber.MethodDelete, "/v1/contacts/:contactID", middlewares, h.Delete)
+}
+
+// Index lists contacts for the authenticated user.
+// @Summary      List contacts
+// @Description  Returns the paginated list of contacts for the authenticated user.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param        skip	query  int  	false	"number of contacts to skip"	minimum(0)
+// @Param        query	query  string  	false 	"filter contacts containing query"
+// @Param        limit	query  int  	false	"number of contacts to return"	minimum(1)	maximum(100)
+// @Success      200 	{object}	responses.ContactsResponse
+// @Failure      400	{object}	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure      422	{object}	responses.UnprocessableEntity
+// @Failure      500	{object}	responses.InternalServerError
+// @Router       /contacts [get]
+func (h *ContactHandler) Index(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	var request requests.ContactIndex
+	if err := c.Bind().Query(&request); err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall params [%s] into %T", c.OriginalURL(), request))
+		return h.responseBadRequest(c, err)
+	}
+
+	sanitized := request.Sanitize()
+	if errors := h.validator.ValidateIndex(ctx, sanitized); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while listing contacts [%+#v]", spew.Sdump(errors), sanitized))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while listing contacts")
+	}
+
+	contacts, err := h.service.Index(ctx, h.userIDFomContext(c), sanitized.ToIndexParams())
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot list contacts for user [%s]", h.userIDFomContext(c)))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseOK(c, fmt.Sprintf("fetched %d %s", len(*contacts), h.pluralize("contact", len(*contacts))), contacts)
+}
+
+// Store creates one or many contacts.
+// @Summary      Create one or many contacts
+// @Description  Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a "contacts" array.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param        payload   body 		requests.ContactStoreRequest 	true 	"Contact(s) to create"
+// @Success      201 	{object}	responses.ContactsResponse
+// @Failure      400	{object}	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure      422	{object}	responses.UnprocessableEntity
+// @Failure      500	{object}	responses.InternalServerError
+// @Router       /contacts [post]
+func (h *ContactHandler) Store(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	var request requests.ContactStoreRequest
+	if err := c.Bind().Body(&request); err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body [%s] into %T", c.Body(), request))
+		return h.responseBadRequest(c, err)
+	}
+
+	sanitized := request.Sanitize()
+	if errors := h.validator.ValidateStore(ctx, sanitized); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while creating contacts", spew.Sdump(errors)))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while creating contacts")
+	}
+
+	userID := h.userIDFomContext(c)
+	contacts := sanitized.ToContacts(userID)
+	if err := h.service.CreateMany(ctx, userID, contacts); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot create [%d] contacts for user [%s]", len(contacts), userID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseCreated(c, fmt.Sprintf("created %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)
+}
+
+// Upload imports contacts from a CSV file.
+// @Summary      Import contacts from CSV
+// @Description  Uploads a CSV file (multipart field "document") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by ";").
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       multipart/form-data
+// @Produce      json
+// @Param        document	formData	file	true	"CSV file of contacts"
+// @Success      201 	{object}	responses.ContactsResponse
+// @Failure      400	{object}	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure      422	{object}	responses.UnprocessableEntity
+// @Failure      500	{object}	responses.InternalServerError
+// @Router       /contacts/upload [post]
+func (h *ContactHandler) Upload(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	file, err := c.FormFile("document")
+	if err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot fetch file with name [%s] from request", "document"))
+		return h.responseBadRequest(c, err)
+	}
+
+	userID := h.userIDFomContext(c)
+	items, errors := h.validator.ValidateUpload(ctx, userID, file)
+	if len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while importing contacts from CSV [%s]", spew.Sdump(errors), file.Filename))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while importing contacts")
+	}
+
+	request := (requests.ContactStoreRequest{Contacts: items}).Sanitize()
+	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))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseCreated(c, fmt.Sprintf("imported %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)
+}
+
+// Update updates a single contact.
+// @Summary      Update a contact
+// @Description  Updates the details of a single contact.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param 		 contactID	path		string 							true 	"ID of the contact"
+// @Param        payload   	body 		requests.ContactUpdateRequest 	true 	"Contact details to update"
+// @Success      200 		{object}	responses.ContactResponse
+// @Failure      400		{object}	responses.BadRequest
+// @Failure 	 401    	{object}	responses.Unauthorized
+// @Failure      404		{object}	responses.NotFound
+// @Failure      422		{object}	responses.UnprocessableEntity
+// @Failure      500		{object}	responses.InternalServerError
+// @Router       /contacts/{contactID} [put]
+func (h *ContactHandler) Update(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	contactID := c.Params("contactID")
+	if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")
+	}
+
+	var request requests.ContactUpdateRequest
+	if err := c.Bind().Body(&request); err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body into %T", request))
+		return h.responseBadRequest(c, err)
+	}
+
+	sanitized := request.Sanitize()
+	if errors := h.validator.ValidateUpdate(ctx, sanitized); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")
+	}
+
+	userID := h.userIDFomContext(c)
+	contact, err := h.service.Get(ctx, userID, uuid.MustParse(contactID))
+	if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {
+		return h.responseNotFound(c, fmt.Sprintf("cannot find contact with ID [%s]", contactID))
+	}
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot load contact [%s] for user [%s]", contactID, userID))
+		return h.responseInternalServerError(c)
+	}
+
+	sanitized.ApplyTo(contact)
+	if err = h.service.Update(ctx, contact); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot update contact [%s]", contactID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseOK(c, "contact updated successfully", contact)
+}
+
+// Delete removes a single contact.
+// @Summary      Delete a contact
+// @Description  Deletes a single contact from the database.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param 		 contactID	path		string 	true	"ID of the contact"
+// @Success      204  	{object} 	responses.NoContent
+// @Failure      400  	{object}  	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure 	 404	{object}	responses.NotFound
+// @Failure      422  	{object} 	responses.UnprocessableEntity
+// @Failure      500  	{object}  	responses.InternalServerError
+// @Router       /contacts/{contactID} [delete]
+func (h *ContactHandler) Delete(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	contactID := c.Params("contactID")
+	if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while deleting contact [%s]", spew.Sdump(errors), contactID))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while deleting contact")
+	}
+
+	userID := h.userIDFomContext(c)
+	if err := h.service.Delete(ctx, userID, uuid.MustParse(contactID)); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseNoContent(c, "contact deleted successfully")
+}
+```
+
+- [ ] **Step 4: Add DI getters and wiring**
+
+In `api/pkg/di/container.go`:
+
+Add a repository getter (near `MessageThreadRepository`):
+
+```go
+// ContactRepository creates a new instance of repositories.ContactRepository
+func (container *Container) ContactRepository() (repository repositories.ContactRepository) {
+	container.logger.Debug("creating GORM repositories.ContactRepository")
+	return repositories.NewGormContactRepository(
+		container.Logger(),
+		container.Tracer(),
+		container.DB(),
+	)
+}
+```
+
+Add a service getter (near `MessageThreadService`):
+
+```go
+// ContactService creates a new instance of services.ContactService
+func (container *Container) ContactService() (service *services.ContactService) {
+	container.logger.Debug(fmt.Sprintf("creating %T", service))
+	return services.NewContactService(
+		container.Logger(),
+		container.Tracer(),
+		container.ContactRepository(),
+		container.Cache(),
+	)
+}
+```
+
+Add a validator getter (near `MessageThreadHandlerValidator`):
+
+```go
+// ContactHandlerValidator creates a new instance of validators.ContactHandlerValidator
+func (container *Container) ContactHandlerValidator() (validator *validators.ContactHandlerValidator) {
+	container.logger.Debug(fmt.Sprintf("creating %T", validator))
+	return validators.NewContactHandlerValidator(
+		container.Logger(),
+		container.Tracer(),
+	)
+}
+```
+
+Add a handler getter (near `MessageThreadHandler`):
+
+```go
+// ContactHandler creates a new instance of handlers.ContactHandler
+func (container *Container) ContactHandler() (h *handlers.ContactHandler) {
+	container.logger.Debug(fmt.Sprintf("creating %T", h))
+	return handlers.NewContactHandler(
+		container.Logger(),
+		container.Tracer(),
+		container.ContactHandlerValidator(),
+		container.ContactService(),
+	)
+}
+```
+
+Add a route registrar (near `RegisterMessageThreadRoutes`):
+
+```go
+// RegisterContactRoutes registers routes for the /contacts prefix
+func (container *Container) RegisterContactRoutes() {
+	container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.ContactHandler{}))
+	container.ContactHandler().RegisterRoutes(container.App(), container.AuthenticatedMiddleware())
+}
+```
+
+Call the registrar right after `container.RegisterMessageThreadRoutes()` (around line 123):
+
+```go
+	container.RegisterMessageThreadRoutes()
+	container.RegisterContactRoutes()
+```
+
+Wire the ContactService into MessageThreadService (finalise Task 7 Step 5): the `MessageThreadService()` getter's `NewMessageThreadService(...)` call's final argument becomes `container.ContactService()`:
+
+```go
+	return services.NewMessageThreadService(
+		container.Logger(),
+		container.Tracer(),
+		container.MessageThreadRepository(),
+		container.PhoneRepository(),
+		container.EventDispatcher(),
+		container.ContactService(),
+	)
+```
+
+Add the AutoMigrate entry in the AutoMigrate block (around line 413, alongside the other `db.AutoMigrate(&entities.X{})` calls) — this may already be present from Task 2; if not, add:
+
+```go
+	if err = db.AutoMigrate(&entities.Contact{}); err != nil {
+		container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.Contact{}))
+	}
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `cd api && go test -vet=off ./pkg/handlers/ -run TestContactHandler`
+Expected: PASS
+
+- [ ] **Step 6: Build the whole API to confirm wiring compiles**
+
+Run: `cd api && go build ./...`
+Expected: no output (success).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add api/pkg/handlers/contact_handler.go api/pkg/handlers/contact_handler_test.go api/pkg/di/container.go
+git commit -m "feat(api): add ContactHandler and wire contacts into DI container"
+```
+
+---
+
+### Task 9: Swagger regeneration + CSV import template
+
+**Files:**
+- Modify: `api/docs/*` (generated by swag)
+- Create: `web/public/templates/httpsms-contacts.csv`
+- Create/verify: `api/pkg/responses/` contact response types if referenced by Swagger annotations (see Step 1).
+
+**Interfaces:**
+- Consumes: Swagger annotations added on `ContactHandler` (Task 8), which reference `responses.ContactResponse` and `responses.ContactsResponse`.
+- Produces: regenerated `api/docs/swagger.json` / `swagger.yaml` / `docs.go` including the `/contacts` endpoints; a downloadable CSV template served by the web app.
+
+- [ ] **Step 1: Add response wrapper types (if missing)**
+
+Check whether `responses.ContactResponse` and `responses.ContactsResponse` exist:
+
+Run: `cd api && findstr /S /C:"ContactsResponse" pkg\responses\*.go`
+Expected: no matches (they don't exist yet).
+
+Create `api/pkg/responses/contact_responses.go`:
+
+```go
+package responses
+
+import "github.com/NdoleStudio/httpsms/pkg/entities"
+
+// ContactResponse is the response with a single entities.Contact.
+type ContactResponse struct {
+	response
+	Data entities.Contact `json:"data"`
+}
+
+// ContactsResponse is the response with a list of entities.Contact.
+type ContactsResponse struct {
+	response
+	Data []entities.Contact `json:"data"`
+}
+```
+
+(Verify the base embedded type name: open any file in `api/pkg/responses/` and confirm the unexported base struct is `response` with `Status`/`Message` fields; match the exact embed used by e.g. `MessageThreadsResponse`.)
+
+- [ ] **Step 2: Regenerate Swagger docs**
+
+Run:
+
+```bash
+cd api && swag init --requiredByDefault --parseDependency --parseInternal
+```
+
+Expected: `create docs/docs.go`, `create docs/swagger.json`, `create docs/swagger.yaml` with no errors. Confirm `/contacts` appears:
+
+Run: `cd api && findstr /C:"/contacts" docs\swagger.json`
+Expected: matches for `/contacts`, `/contacts/upload`, `/contacts/{contactID}`.
+
+- [ ] **Step 3: Create the CSV import template**
+
+Create `web/public/templates/httpsms-contacts.csv`:
+
+```csv
+Name,Emails,PhoneNumbers
+John Doe,john@example.com,+18005550199
+Jane Smith,jane@example.com;jane.work@example.com,+18005550100;+18005550111
+Acme Support,,+18005550122
+```
+
+(Multiple emails or phone numbers in one cell are separated by `;`, matching the CSV parser in Task 5's `ValidateUpload`.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add api/docs api/pkg/responses/contact_responses.go web/public/templates/httpsms-contacts.csv
+git commit -m "chore(api): regenerate swagger for contacts + add CSV import template"
+```
+
+---
+
+### Task 10: Regenerate web API TypeScript models
+
+**Files:**
+- Modify: `web/shared/types/api.ts` (generated)
+
+**Interfaces:**
+- Consumes: `api/docs/swagger.json` (regenerated in Task 9) with the `Contact` schema and `/contacts` paths.
+- Produces: generated types `EntitiesContact` and (if the response wrappers were added) `ResponsesContactResponse` / `ResponsesContactsResponse` in `web/shared/types/api.ts`; `EntitiesMessageThread` now includes an optional `contact_details?: EntitiesContact`.
+
+> **Note:** This task must run AFTER Task 9 (swagger regen). No new hand-written code — the model file is generated.
+
+- [ ] **Step 1: Regenerate models**
+
+Run:
+
+```bash
+cd web && pnpm api:models
+```
+
+Expected: `web/shared/types/api.ts` rewritten with no errors.
+
+- [ ] **Step 2: Verify the Contact type exists**
+
+Run: `cd web && findstr /C:"EntitiesContact" shared\types\api.ts`
+Expected: matches for `EntitiesContact` interface and `contact_details` on the message-thread interface.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web/shared/types/api.ts
+git commit -m "chore(web): regenerate API models with Contact types"
+```
+
+---
+
+### Task 11: Contacts Pinia store
+
+**Files:**
+- Create: `web/app/stores/contacts.ts`
+
+**Interfaces:**
+- Consumes: `useApi()` (`apiFetch`), `useNotificationsStore()`, `getApiErrorMessage`, `EntitiesContact` (Task 10).
+- Produces: `useContactsStore()` exposing state `contacts`, `loading`, `search`; getters `filteredContacts`, `total`; actions `loadContacts(force?)`, `saveContacts(items)`, `updateContact(id, payload)`, `deleteContact(id)`, `uploadCsv(file)`, `resetState()`.
+
+- [ ] **Step 1: Write the store**
+
+Create `web/app/stores/contacts.ts`:
+
+```ts
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import type { EntitiesContact } from '~~/shared/types/api'
+import { getApiErrorMessage } from '~/utils/api-error'
+
+export interface ContactInput {
+  name: string
+  emails: string[]
+  phone_numbers: string[]
+  properties?: Record<string, string>
+}
+
+export const useContactsStore = defineStore('contacts', () => {
+  const contacts = ref<EntitiesContact[]>([])
+  const loading = ref(false)
+  const search = ref('')
+  const { apiFetch } = useApi()
+  const notificationsStore = useNotificationsStore()
+
+  const total = computed(() => contacts.value.length)
+
+  const filteredContacts = computed<EntitiesContact[]>(() => {
+    const term = search.value.trim().toLowerCase()
+    if (!term) return contacts.value
+    return contacts.value.filter((contact) => {
+      const name = (contact.name ?? '').toLowerCase()
+      const emails = (contact.emails ?? []).join(' ').toLowerCase()
+      const numbers = (contact.phone_numbers ?? []).join(' ').toLowerCase()
+      return (
+        name.includes(term) ||
+        emails.includes(term) ||
+        numbers.includes(term)
+      )
+    })
+  })
+
+  async function loadContacts(force = false) {
+    if (contacts.value.length > 0 && !force) return
+    loading.value = true
+    try {
+      const response = await apiFetch<{ data: EntitiesContact[] }>(
+        '/v1/contacts',
+        { params: { limit: 100 } },
+      )
+      contacts.value = response.data ?? []
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while loading contacts'),
+        type: 'error',
+      })
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function saveContacts(items: ContactInput[]) {
+    try {
+      await apiFetch('/v1/contacts', { method: 'POST', body: items })
+      notificationsStore.addNotification({
+        message:
+          items.length > 1 ? 'Contacts created' : 'Contact created',
+        type: 'success',
+      })
+      await loadContacts(true)
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while saving contacts'),
+        type: 'error',
+      })
+      throw error
+    }
+  }
+
+  async function updateContact(id: string, payload: ContactInput) {
+    try {
+      await apiFetch(`/v1/contacts/${id}`, { method: 'PUT', body: payload })
+      notificationsStore.addNotification({
+        message: 'Contact updated',
+        type: 'success',
+      })
+      await loadContacts(true)
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while updating contact'),
+        type: 'error',
+      })
+      throw error
+    }
+  }
+
+  async function deleteContact(id: string) {
+    try {
+      await apiFetch(`/v1/contacts/${id}`, { method: 'DELETE' })
+      contacts.value = contacts.value.filter((contact) => contact.id !== id)
+      notificationsStore.addNotification({
+        message: 'Contact deleted',
+        type: 'success',
+      })
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while deleting contact'),
+        type: 'error',
+      })
+      throw error
+    }
+  }
+
+  async function uploadCsv(file: File) {
+    try {
+      const formData = new FormData()
+      formData.append('document', file)
+      await apiFetch('/v1/contacts/upload', {
+        method: 'POST',
+        body: formData,
+      })
+      notificationsStore.addNotification({
+        message: 'Contacts imported successfully',
+        type: 'success',
+      })
+      await loadContacts(true)
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while importing contacts'),
+        type: 'error',
+      })
+      throw error
+    }
+  }
+
+  function resetState() {
+    contacts.value = []
+    loading.value = false
+    search.value = ''
+  }
+
+  return {
+    contacts,
+    loading,
+    search,
+    total,
+    filteredContacts,
+    loadContacts,
+    saveContacts,
+    updateContact,
+    deleteContact,
+    uploadCsv,
+    resetState,
+  }
+})
+```
+
+- [ ] **Step 2: Lint the new store**
+
+Run: `cd web && pnpm lint:js`
+Expected: no errors for `app/stores/contacts.ts`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web/app/stores/contacts.ts
+git commit -m "feat(web): add contacts Pinia store"
+```
+
+---
+
+### Task 12: Contacts page with add/edit/delete/import dialogs
+
+**Files:**
+- Create: `web/app/pages/contacts/index.vue`
+
+**Interfaces:**
+- Consumes: `useContactsStore()` (Task 11), `useFilters()` (`formatPhoneNumber`), `EntitiesContact` (Task 10).
+- Produces: the `/contacts` route (Nuxt file-based routing infers `name: 'contacts'`, used by the nav link in Task 13).
+
+**UI requirements (from spec section 7 / reference screenshot):**
+- Page title `text-display-large` (NO gradient/glow — theme text only); subtitle showing total contact count.
+- Top-right actions: "Import CSV" (outlined button) + "Add Contact" (filled `color="primary"` button).
+- Debounced search field filtering by name/email/phone.
+- Table of contacts (Name, Emails, Phone Numbers) with edit + delete icon actions per row.
+- Add/Edit/Delete/Import are `VDialog`s. **Every `VDialog` MUST set `opacity="0.9"` and its Close button MUST use `color="warning"`.**
+
+- [ ] **Step 1: Write the page**
+
+Create `web/app/pages/contacts/index.vue`:
+
+```vue
+<script setup lang="ts">
+import {
+  mdiArrowLeft,
+  mdiPlus,
+  mdiFileUpload,
+  mdiPencil,
+  mdiDelete,
+  mdiMagnify,
+  mdiClose,
+} from '@mdi/js'
+import { ref, computed, onMounted } from 'vue'
+import type { EntitiesContact } from '~~/shared/types/api'
+import { useContactsStore, type ContactInput } from '~/stores/contacts'
+import { useFilters } from '~/composables/useFilters'
+
+definePageMeta({
+  middleware: ['auth'],
+})
+
+useHead({
+  title: 'Contacts - httpSMS',
+})
+
+const contactsStore = useContactsStore()
+const { formatPhoneNumber } = useFilters()
+
+const editDialog = ref(false)
+const deleteDialog = ref(false)
+const importDialog = ref(false)
+const saving = ref(false)
+const editingId = ref<string | null>(null)
+const pendingDeleteId = ref<string | null>(null)
+const importFile = ref<File | null>(null)
+
+const form = ref<{ name: string; emails: string; phone_numbers: string }>({
+  name: '',
+  emails: '',
+  phone_numbers: '',
+})
+
+const dialogTitle = computed(() =>
+  editingId.value ? 'Edit Contact' : 'Add Contact',
+)
+
+function splitList(value: string): string[] {
+  return value
+    .split(/[,;]/)
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+}
+
+function openAdd() {
+  editingId.value = null
+  form.value = { name: '', emails: '', phone_numbers: '' }
+  editDialog.value = true
+}
+
+function openEdit(contact: EntitiesContact) {
+  editingId.value = contact.id ?? null
+  form.value = {
+    name: contact.name ?? '',
+    emails: (contact.emails ?? []).join(', '),
+    phone_numbers: (contact.phone_numbers ?? []).join(', '),
+  }
+  editDialog.value = true
+}
+
+function openDelete(contact: EntitiesContact) {
+  pendingDeleteId.value = contact.id ?? null
+  deleteDialog.value = true
+}
+
+async function submitForm() {
+  saving.value = true
+  const payload: ContactInput = {
+    name: form.value.name.trim(),
+    emails: splitList(form.value.emails),
+    phone_numbers: splitList(form.value.phone_numbers),
+  }
+  try {
+    if (editingId.value) {
+      await contactsStore.updateContact(editingId.value, payload)
+    } else {
+      await contactsStore.saveContacts([payload])
+    }
+    editDialog.value = false
+  } catch {
+    // notification already surfaced by the store
+  } finally {
+    saving.value = false
+  }
+}
+
+async function confirmDelete() {
+  if (!pendingDeleteId.value) return
+  saving.value = true
+  try {
+    await contactsStore.deleteContact(pendingDeleteId.value)
+    deleteDialog.value = false
+  } catch {
+    // notification already surfaced by the store
+  } finally {
+    saving.value = false
+    pendingDeleteId.value = null
+  }
+}
+
+async function submitImport() {
+  if (!importFile.value) return
+  saving.value = true
+  try {
+    await contactsStore.uploadCsv(importFile.value)
+    importDialog.value = false
+    importFile.value = null
+  } catch {
+    // notification already surfaced by the store
+  } finally {
+    saving.value = false
+  }
+}
+
+onMounted(() => {
+  contactsStore.loadContacts(true).catch(() => {})
+})
+</script>
+
+<template>
+  <VContainer fluid class="px-0 pt-0">
+    <VAppBar>
+      <VBtn icon to="/threads">
+        <VIcon :icon="mdiArrowLeft" />
+      </VBtn>
+      <VToolbarTitle>Contacts</VToolbarTitle>
+      <VProgressLinear
+        :active="contactsStore.loading"
+        color="primary"
+        :indeterminate="contactsStore.loading"
+        location="bottom"
+        absolute
+      />
+    </VAppBar>
+
+    <VContainer>
+      <VRow>
+        <VCol cols="12" md="10" offset-md="1" xxl="8" offset-xxl="2">
+          <div
+            class="d-flex flex-column flex-md-row align-md-center mb-6 mt-3"
+          >
+            <div>
+              <h1 class="text-display-large">Contacts</h1>
+              <p class="text-medium-emphasis mb-0">
+                {{ contactsStore.total }}
+                {{ contactsStore.total === 1 ? 'contact' : 'contacts' }}
+              </p>
+            </div>
+            <VSpacer />
+            <div class="d-flex mt-4 mt-md-0">
+              <VBtn
+                variant="outlined"
+                color="primary"
+                :prepend-icon="mdiFileUpload"
+                class="mr-3"
+                @click="importDialog = true"
+              >
+                Import CSV
+              </VBtn>
+              <VBtn
+                color="primary"
+                :prepend-icon="mdiPlus"
+                @click="openAdd"
+              >
+                Add Contact
+              </VBtn>
+            </div>
+          </div>
+
+          <VTextField
+            v-model="contactsStore.search"
+            :prepend-inner-icon="mdiMagnify"
+            label="Search contacts"
+            variant="outlined"
+            density="comfortable"
+            clearable
+            hide-details
+            class="mb-4"
+          />
+
+          <VTable density="comfortable">
+            <thead>
+              <tr class="text-uppercase text-medium-emphasis">
+                <th class="text-left">Name</th>
+                <th class="text-left">Emails</th>
+                <th class="text-left">Phone Numbers</th>
+                <th class="text-right">Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr
+                v-for="contact in contactsStore.filteredContacts"
+                :key="contact.id"
+              >
+                <td class="text-left">{{ contact.name }}</td>
+                <td class="text-left">
+                  {{ (contact.emails ?? []).join(', ') }}
+                </td>
+                <td class="text-left">
+                  {{
+                    (contact.phone_numbers ?? [])
+                      .map((number) => formatPhoneNumber(number))
+                      .join(', ')
+                  }}
+                </td>
+                <td class="text-right">
+                  <VBtn
+                    icon
+                    variant="text"
+                    size="small"
+                    @click="openEdit(contact)"
+                  >
+                    <VIcon :icon="mdiPencil" />
+                  </VBtn>
+                  <VBtn
+                    icon
+                    variant="text"
+                    size="small"
+                    color="error"
+                    @click="openDelete(contact)"
+                  >
+                    <VIcon :icon="mdiDelete" />
+                  </VBtn>
+                </td>
+              </tr>
+              <tr v-if="contactsStore.filteredContacts.length === 0">
+                <td colspan="4" class="text-center text-medium-emphasis py-8">
+                  No contacts found.
+                </td>
+              </tr>
+            </tbody>
+          </VTable>
+        </VCol>
+      </VRow>
+    </VContainer>
+
+    <!-- Add / Edit dialog -->
+    <VDialog v-model="editDialog" max-width="560" opacity="0.9">
+      <VCard>
+        <VCardTitle class="d-flex align-center">
+          <span>{{ dialogTitle }}</span>
+          <VSpacer />
+          <VBtn
+            icon
+            variant="text"
+            color="warning"
+            @click="editDialog = false"
+          >
+            <VIcon :icon="mdiClose" />
+          </VBtn>
+        </VCardTitle>
+        <VCardText>
+          <VTextField
+            v-model="form.name"
+            label="Name"
+            variant="outlined"
+            class="mb-2"
+          />
+          <VTextField
+            v-model="form.emails"
+            label="Emails (comma separated)"
+            variant="outlined"
+            class="mb-2"
+          />
+          <VTextField
+            v-model="form.phone_numbers"
+            label="Phone numbers (comma separated)"
+            variant="outlined"
+          />
+        </VCardText>
+        <VCardActions>
+          <VSpacer />
+          <VBtn color="warning" variant="text" @click="editDialog = false">
+            Close
+          </VBtn>
+          <VBtn
+            color="primary"
+            :loading="saving"
+            :disabled="saving"
+            @click="submitForm"
+          >
+            Save
+          </VBtn>
+        </VCardActions>
+      </VCard>
+    </VDialog>
+
+    <!-- Delete dialog -->
+    <VDialog v-model="deleteDialog" max-width="460" opacity="0.9">
+      <VCard>
+        <VCardTitle class="d-flex align-center">
+          <span>Delete Contact</span>
+          <VSpacer />
+          <VBtn
+            icon
+            variant="text"
+            color="warning"
+            @click="deleteDialog = false"
+          >
+            <VIcon :icon="mdiClose" />
+          </VBtn>
+        </VCardTitle>
+        <VCardText>
+          Are you sure you want to delete this contact? This action cannot be
+          undone.
+        </VCardText>
+        <VCardActions>
+          <VSpacer />
+          <VBtn color="warning" variant="text" @click="deleteDialog = false">
+            Close
+          </VBtn>
+          <VBtn
+            color="error"
+            :loading="saving"
+            :disabled="saving"
+            @click="confirmDelete"
+          >
+            Delete
+          </VBtn>
+        </VCardActions>
+      </VCard>
+    </VDialog>
+
+    <!-- Import CSV dialog -->
+    <VDialog v-model="importDialog" max-width="560" opacity="0.9">
+      <VCard>
+        <VCardTitle class="d-flex align-center">
+          <span>Import Contacts from CSV</span>
+          <VSpacer />
+          <VBtn
+            icon
+            variant="text"
+            color="warning"
+            @click="importDialog = false"
+          >
+            <VIcon :icon="mdiClose" />
+          </VBtn>
+        </VCardTitle>
+        <VCardText>
+          <p class="mb-3">
+            Download our
+            <a
+              class="text-decoration-none hover:text-decoration-underline"
+              download
+              href="/templates/httpsms-contacts.csv"
+              >CSV template</a
+            >, fill it in and upload it here. Columns: Name, Emails,
+            PhoneNumbers (multiple values separated by ";").
+          </p>
+          <VFileInput
+            v-model="importFile"
+            label="CSV file"
+            color="primary"
+            accept=".csv,text/csv"
+            variant="outlined"
+            hide-details
+          />
+        </VCardText>
+        <VCardActions>
+          <VSpacer />
+          <VBtn color="warning" variant="text" @click="importDialog = false">
+            Close
+          </VBtn>
+          <VBtn
+            color="primary"
+            :loading="saving"
+            :disabled="saving || !importFile"
+            @click="submitImport"
+          >
+            Import
+          </VBtn>
+        </VCardActions>
+      </VCard>
+    </VDialog>
+  </VContainer>
+</template>
+```
+
+- [ ] **Step 2: Lint the page**
+
+Run: `cd web && pnpm lint:js && pnpm lint:prettier`
+Expected: no errors for `app/pages/contacts/index.vue`. If Prettier reports formatting, run `pnpm lintfix` and re-check.
+
+- [ ] **Step 3: Build the site to confirm it compiles**
+
+Run: `cd web && pnpm generate`
+Expected: build completes without type errors (the `/contacts` route is emitted).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/app/pages/contacts/index.vue
+git commit -m "feat(web): add contacts page with add/edit/delete/import dialogs"
+```
+
+---
+
+### Task 13: Show contact names on threads + Contacts nav link
+
+**Files:**
+- Modify: `web/app/stores/threads.ts` (send `contacts: true`)
+- Modify: `web/app/components/MessageThread.vue` (list title + avatar initial)
+- Modify: `web/app/pages/threads/[id]/index.vue` (toolbar title)
+- Modify: `web/app/components/MessageThreadHeader.vue` (Contacts nav item + icon import)
+
+**Interfaces:**
+- Consumes: `EntitiesMessageThread.contact_details?: EntitiesContact` (Task 10), the `/contacts` route (Task 12).
+- Produces: no new exports — UI wiring only.
+
+- [ ] **Step 1: Request contact resolution when loading threads**
+
+In `web/app/stores/threads.ts`, add `contacts: true` to the `loadThreads` request params:
+
+```ts
+    const response = await apiFetch<{ data: EntitiesMessageThread[] }>(
+      '/v1/message-threads',
+      {
+        params: {
+          owner: phonesStore.owner ?? phonesStore.phones[0]?.phone_number,
+          limit: 100,
+          is_archived: archivedThreads.value,
+          contacts: true,
+        },
+      },
+    )
+```
+
+- [ ] **Step 2: Show the contact name in the threads list**
+
+In `web/app/components/MessageThread.vue`, replace the list-item title expression:
+
+```vue
+        <v-list-item-title :class="{ 'font-weight-bold': !thread.is_read }">{{
+          thread.contact_details?.name ?? formatPhoneNumber(thread.contact)
+        }}</v-list-item-title>
+```
+
+And update the avatar initial to prefer the contact name (replace the existing `<template #prepend>` avatar content):
+
+```vue
+        <template #prepend>
+          <v-avatar
+            :color="thread.color"
+            size="40"
+            :badge="thread.is_read ? false : { color: 'primary', dotSize: 12 }"
+          >
+            <v-icon
+              v-if="!(thread.contact_details?.name || startsWithLetter(thread.contact))"
+              color="white"
+              >{{ mdiAccount }}</v-icon
+            >
+            <span v-else class="text-white text-headline-small">{{
+              (thread.contact_details?.name ?? thread.contact).substring(0, 1)
+            }}</span>
+          </v-avatar>
+        </template>
+```
+
+- [ ] **Step 3: Show the contact name in the thread header**
+
+In `web/app/pages/threads/[id]/index.vue`, replace the toolbar title expression (around line 271):
+
+```vue
+        <VToolbarTitle v-if="threadsStore.currentThread">
+          {{
+            threadsStore.currentThread.contact_details?.name ??
+            formatPhoneNumber(threadsStore.currentThread.contact)
+          }}
+        </VToolbarTitle>
+```
+
+- [ ] **Step 4: Add the Contacts navigation item**
+
+In `web/app/components/MessageThreadHeader.vue`, add `mdiAccountMultiple` to the `@mdi/js` import block:
+
+```ts
+  mdiCommentTextMultipleOutline,
+  mdiAccountMultiple,
+  mdiCircle,
+```
+
+Add a nav item right after the "Search Messages" `v-list-item` (before the Settings item):
+
+```vue
+        <v-list-item :to="{ name: 'contacts' }">
+          <template #prepend><v-icon :icon="mdiAccountMultiple" /></template>
+          <v-list-item-title>Contacts</v-list-item-title>
+        </v-list-item>
+```
+
+- [ ] **Step 5: Lint and build**
+
+Run: `cd web && pnpm lint:js && pnpm generate`
+Expected: no errors; the build succeeds.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add web/app/stores/threads.ts web/app/components/MessageThread.vue web/app/pages/threads/[id]/index.vue web/app/components/MessageThreadHeader.vue
+git commit -m "feat(web): display contact names on threads and add Contacts nav link"
+```
+
+---
+
+## Final Verification
+
+- [ ] **API full test + build**
+
+```bash
+cd api && go test -vet=off ./... && go build ./...
+```
+Expected: all packages pass; build succeeds.
+
+- [ ] **Web lint + build**
+
+```bash
+cd web && pnpm lint && pnpm generate
+```
+Expected: lint clean; static build succeeds.
+
+- [ ] **Manual smoke test (optional, with Docker stack)**
+
+```bash
+docker compose up --build
+```
+Then: create a contact via `POST /v1/contacts`, load `/threads` and confirm the contact name shows for a matching phone number; open `/contacts` and exercise add/edit/delete/import.

From ba045033379121e73ce8c8b4e5fa93d9082703aa Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 21:21:18 +0300
Subject: [PATCH 02/24] feat(api): add Contact entity and ContactProperties
 jsonb type

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/entities/contact.go      | 76 ++++++++++++++++++++++++++++++++
 api/pkg/entities/contact_test.go | 41 +++++++++++++++++
 2 files changed, 117 insertions(+)
 create mode 100644 api/pkg/entities/contact.go
 create mode 100644 api/pkg/entities/contact_test.go

diff --git a/api/pkg/entities/contact.go b/api/pkg/entities/contact.go
new file mode 100644
index 000000000..f3342e154
--- /dev/null
+++ b/api/pkg/entities/contact.go
@@ -0,0 +1,76 @@
+package entities
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+)
+
+// ContactProperties is a free-form key/value map persisted as a jsonb column.
+type ContactProperties map[string]string
+
+// Value implements driver.Valuer, serializing the map to JSON bytes.
+func (p ContactProperties) Value() (driver.Value, error) {
+	if p == nil {
+		return []byte("{}"), nil
+	}
+
+	data, err := json.Marshal(p)
+	if err != nil {
+		return nil, err
+	}
+
+	return data, nil
+}
+
+// Scan implements sql.Scanner, deserializing jsonb bytes/string into the map.
+func (p *ContactProperties) Scan(src any) error {
+	if src == nil {
+		*p = ContactProperties{}
+		return nil
+	}
+
+	var data []byte
+	switch value := src.(type) {
+	case []byte:
+		data = value
+	case string:
+		data = []byte(value)
+	default:
+		return fmt.Errorf("unsupported type [%T] for ContactProperties", src)
+	}
+
+	if len(data) == 0 {
+		*p = ContactProperties{}
+		return nil
+	}
+
+	result := ContactProperties{}
+	if err := json.Unmarshal(data, &result); err != nil {
+		return err
+	}
+
+	*p = result
+	return nil
+}
+
+// Contact represents a saved contact belonging to a user.
+type Contact struct {
+	ID           uuid.UUID         `json:"id" gorm:"primaryKey;type:uuid;" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`
+	UserID       UserID            `json:"user_id" gorm:"index" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`
+	Name         string            `json:"name" example:"Alice Smith"`
+	Emails       pq.StringArray    `json:"emails" gorm:"type:text[]" swaggertype:"array,string" example:"alice@example.com"`
+	PhoneNumbers pq.StringArray    `json:"phone_numbers" gorm:"type:text[]" swaggertype:"array,string" example:"+18005550199,+18005550100"`
+	Properties   ContactProperties `json:"properties" gorm:"type:jsonb" swaggertype:"object,string"`
+	CreatedAt    time.Time         `json:"created_at" example:"2022-06-05T14:26:02.302718+03:00"`
+	UpdatedAt    time.Time         `json:"updated_at" example:"2022-06-05T14:26:02.302718+03:00"`
+}
+
+// TableName overrides the table name used by Contact.
+func (Contact) TableName() string {
+	return "contacts"
+}
diff --git a/api/pkg/entities/contact_test.go b/api/pkg/entities/contact_test.go
new file mode 100644
index 000000000..6e2091101
--- /dev/null
+++ b/api/pkg/entities/contact_test.go
@@ -0,0 +1,41 @@
+package entities
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestContactProperties_ValueScanRoundTrip(t *testing.T) {
+	cases := []ContactProperties{
+		nil,
+		{},
+		{"company": "Acme", "role": "CTO"},
+	}
+
+	for _, original := range cases {
+		value, err := original.Value()
+		assert.Nil(t, err)
+
+		var scanned ContactProperties
+		assert.Nil(t, scanned.Scan(value))
+
+		if len(original) == 0 {
+			assert.Equal(t, 0, len(scanned))
+			continue
+		}
+		assert.Equal(t, original, scanned)
+	}
+}
+
+func TestContactProperties_ScanFromString(t *testing.T) {
+	var scanned ContactProperties
+	assert.Nil(t, scanned.Scan(`{"k":"v"}`))
+	assert.Equal(t, ContactProperties{"k": "v"}, scanned)
+}
+
+func TestContactProperties_ScanNil(t *testing.T) {
+	var scanned ContactProperties
+	assert.Nil(t, scanned.Scan(nil))
+	assert.Equal(t, 0, len(scanned))
+}

From d0e5b40e7ec64ecfb873cd1aad316cad23b29d16 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 21:26:47 +0300
Subject: [PATCH 03/24] fix(api): wrap contact property errors

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/entities/contact.go      | 10 +++++-----
 api/pkg/entities/contact_test.go | 11 +++++++++++
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/api/pkg/entities/contact.go b/api/pkg/entities/contact.go
index f3342e154..ecc47a421 100644
--- a/api/pkg/entities/contact.go
+++ b/api/pkg/entities/contact.go
@@ -3,9 +3,9 @@ package entities
 import (
 	"database/sql/driver"
 	"encoding/json"
-	"fmt"
 	"time"
 
+	"github.com/NdoleStudio/stacktrace"
 	"github.com/google/uuid"
 	"github.com/lib/pq"
 )
@@ -21,7 +21,7 @@ func (p ContactProperties) Value() (driver.Value, error) {
 
 	data, err := json.Marshal(p)
 	if err != nil {
-		return nil, err
+		return nil, stacktrace.Propagatef(err, "cannot marshal ContactProperties")
 	}
 
 	return data, nil
@@ -41,7 +41,7 @@ func (p *ContactProperties) Scan(src any) error {
 	case string:
 		data = []byte(value)
 	default:
-		return fmt.Errorf("unsupported type [%T] for ContactProperties", src)
+		return stacktrace.NewErrorf("unsupported type [%T] for ContactProperties", src)
 	}
 
 	if len(data) == 0 {
@@ -51,7 +51,7 @@ func (p *ContactProperties) Scan(src any) error {
 
 	result := ContactProperties{}
 	if err := json.Unmarshal(data, &result); err != nil {
-		return err
+		return stacktrace.Propagatef(err, "cannot unmarshal ContactProperties")
 	}
 
 	*p = result
@@ -60,7 +60,7 @@ func (p *ContactProperties) Scan(src any) error {
 
 // Contact represents a saved contact belonging to a user.
 type Contact struct {
-	ID           uuid.UUID         `json:"id" gorm:"primaryKey;type:uuid;" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`
+	ID           uuid.UUID         `json:"id" gorm:"primaryKey;type:uuid" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`
 	UserID       UserID            `json:"user_id" gorm:"index" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`
 	Name         string            `json:"name" example:"Alice Smith"`
 	Emails       pq.StringArray    `json:"emails" gorm:"type:text[]" swaggertype:"array,string" example:"alice@example.com"`
diff --git a/api/pkg/entities/contact_test.go b/api/pkg/entities/contact_test.go
index 6e2091101..537adfbea 100644
--- a/api/pkg/entities/contact_test.go
+++ b/api/pkg/entities/contact_test.go
@@ -1,6 +1,7 @@
 package entities
 
 import (
+	"reflect"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -39,3 +40,13 @@ func TestContactProperties_ScanNil(t *testing.T) {
 	assert.Nil(t, scanned.Scan(nil))
 	assert.Equal(t, 0, len(scanned))
 }
+
+func TestContactProperties_ScanUnsupportedType(t *testing.T) {
+	var scanned ContactProperties
+
+	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")
+}

From c8e86d0e8ca20945bbb5f6c281b13d7b03595915 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 21:31:12 +0300
Subject: [PATCH 04/24] feat(api): add ContactDetails to message threads

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/di/container.go                 |  4 ++++
 api/pkg/entities/message_thread.go      |  2 ++
 api/pkg/entities/message_thread_test.go | 18 ++++++++++++++++++
 3 files changed, 24 insertions(+)

diff --git a/api/pkg/di/container.go b/api/pkg/di/container.go
index ad9a18858..043c897ab 100644
--- a/api/pkg/di/container.go
+++ b/api/pkg/di/container.go
@@ -414,6 +414,10 @@ ALTER TABLE discords ADD CONSTRAINT IF NOT EXISTS uni_discords_server_id CHECK (
 		container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.PhoneAPIKey{}))
 	}
 
+	if err = db.AutoMigrate(&entities.Contact{}); err != nil {
+		container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.Contact{}))
+	}
+
 	return container.db
 }
 
diff --git a/api/pkg/entities/message_thread.go b/api/pkg/entities/message_thread.go
index 3766acc77..d4d893a49 100644
--- a/api/pkg/entities/message_thread.go
+++ b/api/pkg/entities/message_thread.go
@@ -22,6 +22,8 @@ type MessageThread struct {
 	CreatedAt          time.Time     `json:"created_at" example:"2022-06-05T14:26:09.527976+03:00"`
 	UpdatedAt          time.Time     `json:"updated_at" example:"2022-06-05T14:26:09.527976+03:00"`
 	OrderTimestamp     time.Time     `json:"order_timestamp" example:"2022-06-05T14:26:09.527976+03:00"`
+	// ContactDetails is resolved at read time and never persisted.
+	ContactDetails *Contact `json:"contact_details,omitempty" gorm:"-"`
 }
 
 // Update a message thread after a message event
diff --git a/api/pkg/entities/message_thread_test.go b/api/pkg/entities/message_thread_test.go
index 1409dff29..b587bacbc 100644
--- a/api/pkg/entities/message_thread_test.go
+++ b/api/pkg/entities/message_thread_test.go
@@ -1,6 +1,7 @@
 package entities
 
 import (
+	"encoding/json"
 	"reflect"
 	"testing"
 
@@ -23,3 +24,20 @@ func TestMessageThreadReadFieldsHaveBackwardCompatibleDefaults(t *testing.T) {
 	assert.Contains(t, lastReadAt.Tag.Get("gorm"), "default:CURRENT_TIMESTAMP")
 	assert.Equal(t, "-", lastReadAt.Tag.Get("json"))
 }
+
+func TestMessageThreadContactDetailsAreTransientAndOmittedWhenNil(t *testing.T) {
+	threadType := reflect.TypeOf(MessageThread{})
+
+	contactDetails, ok := threadType.FieldByName("ContactDetails")
+	require.True(t, ok)
+	assert.Equal(t, "*entities.Contact", contactDetails.Type.String())
+	assert.Equal(t, "contact_details,omitempty", contactDetails.Tag.Get("json"))
+	assert.Equal(t, "-", contactDetails.Tag.Get("gorm"))
+
+	data, err := json.Marshal(MessageThread{})
+	require.NoError(t, err)
+
+	var payload map[string]any
+	require.NoError(t, json.Unmarshal(data, &payload))
+	assert.NotContains(t, payload, "contact_details")
+}

From 1296729bc6b22ae1f701ae535fe53219bb8db1c0 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 21:44:43 +0300
Subject: [PATCH 05/24] feat(api): add ContactRepository with GORM
 implementation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/repositories/contact_repository.go    |  32 ++
 .../repositories/gorm_contact_repository.go   | 142 +++++++++
 .../gorm_contact_repository_test.go           | 280 ++++++++++++++++++
 3 files changed, 454 insertions(+)
 create mode 100644 api/pkg/repositories/contact_repository.go
 create mode 100644 api/pkg/repositories/gorm_contact_repository.go
 create mode 100644 api/pkg/repositories/gorm_contact_repository_test.go

diff --git a/api/pkg/repositories/contact_repository.go b/api/pkg/repositories/contact_repository.go
new file mode 100644
index 000000000..a03df1948
--- /dev/null
+++ b/api/pkg/repositories/contact_repository.go
@@ -0,0 +1,32 @@
+package repositories
+
+import (
+	"context"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/google/uuid"
+)
+
+// ContactRepository loads and persists an entities.Contact.
+type ContactRepository interface {
+	// Store one or many new entities.Contact.
+	Store(ctx context.Context, contacts []*entities.Contact) error
+
+	// Update an existing entities.Contact.
+	Update(ctx context.Context, contact *entities.Contact) error
+
+	// Load a contact by ID for a user.
+	Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)
+
+	// Index contacts for a user with optional search.
+	Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)
+
+	// FetchAll returns every contact for a user ordered by updated_at ascending.
+	FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)
+
+	// Delete a contact by ID for a user.
+	Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error
+
+	// DeleteAllForUser deletes all contacts for a user.
+	DeleteAllForUser(ctx context.Context, userID entities.UserID) error
+}
diff --git a/api/pkg/repositories/gorm_contact_repository.go b/api/pkg/repositories/gorm_contact_repository.go
new file mode 100644
index 000000000..cebb38678
--- /dev/null
+++ b/api/pkg/repositories/gorm_contact_repository.go
@@ -0,0 +1,142 @@
+package repositories
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+// gormContactRepository is responsible for persisting entities.Contact.
+type gormContactRepository struct {
+	logger telemetry.Logger
+	tracer telemetry.Tracer
+	db     *gorm.DB
+}
+
+// NewGormContactRepository creates the GORM version of the ContactRepository.
+func NewGormContactRepository(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	db *gorm.DB,
+) ContactRepository {
+	return &gormContactRepository{
+		logger: logger.WithService(fmt.Sprintf("%T", &gormContactRepository{})),
+		tracer: tracer,
+		db:     db,
+	}
+}
+
+func (repository *gormContactRepository) Store(ctx context.Context, contacts []*entities.Contact) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if len(contacts) == 0 {
+		return nil
+	}
+
+	if err := repository.db.WithContext(ctx).Create(&contacts).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts", len(contacts)))
+	}
+
+	return nil
+}
+
+func (repository *gormContactRepository) Update(ctx context.Context, contact *entities.Contact) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if err := repository.db.WithContext(ctx).Save(contact).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact with ID [%s]", contact.ID))
+	}
+
+	return nil
+}
+
+func (repository *gormContactRepository) Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	contact := new(entities.Contact)
+	err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Where("id = ?", contactID).
+		First(contact).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, ErrCodeNotFound, "contact with ID [%s] for user [%s] does not exist", contactID, userID))
+	}
+
+	if err != nil {
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot load contact with ID [%s] for user [%s]", contactID, userID))
+	}
+
+	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(
+			repository.db.WithContext(ctx).Where("name ILIKE ?", queryPattern).
+				Or("array_to_string(emails, ',') ILIKE ?", queryPattern).
+				Or("array_to_string(phone_numbers, ',') ILIKE ?", queryPattern),
+		)
+	}
+
+	contacts := new([]entities.Contact)
+	if err := 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) FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error) {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	contacts := new([]entities.Contact)
+	if err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Order("updated_at ASC").
+		Find(contacts).Error; err != nil {
+		return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch all contacts for user [%s]", userID))
+	}
+
+	return contacts, nil
+}
+
+func (repository *gormContactRepository) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	err := repository.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Where("id = ?", contactID).
+		Delete(&entities.Contact{}).Error
+	if err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact with ID [%s] for user [%s]", contactID, userID))
+	}
+
+	return nil
+}
+
+func (repository *gormContactRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {
+	ctx, span := repository.tracer.Start(ctx)
+	defer span.End()
+
+	if err := repository.db.WithContext(ctx).Where("user_id = ?", userID).Delete(&entities.Contact{}).Error; err != nil {
+		return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete all contacts for user [%s]", userID))
+	}
+
+	return nil
+}
diff --git a/api/pkg/repositories/gorm_contact_repository_test.go b/api/pkg/repositories/gorm_contact_repository_test.go
new file mode 100644
index 000000000..b30b7d086
--- /dev/null
+++ b/api/pkg/repositories/gorm_contact_repository_test.go
@@ -0,0 +1,280 @@
+package repositories
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"io"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+func normalizeContactSQL(query string) string {
+	return strings.Join(strings.Fields(query), " ")
+}
+
+type contactTestConnPool struct {
+	messageThreadTestConnPool
+}
+
+func (pool *contactTestConnPool) QueryContext(_ context.Context, query string, args ...any) (*sql.Rows, error) {
+	pool.statements = append(pool.statements, messageThreadTestStatement{
+		query: query,
+		args:  append([]any(nil), args...),
+	})
+
+	db := sql.OpenDB(contactTestRowsConnector{})
+	return db.QueryContext(context.Background(), "SELECT 1")
+}
+
+func (pool *contactTestConnPool) BeginTx(context.Context, *sql.TxOptions) (gorm.ConnPool, error) {
+	return pool, nil
+}
+
+type contactTestRowsConnector struct{}
+
+func (contactTestRowsConnector) Connect(context.Context) (driver.Conn, error) {
+	return contactTestRowsConn{}, nil
+}
+
+func (contactTestRowsConnector) Driver() driver.Driver {
+	return contactTestRowsDriver{}
+}
+
+type contactTestRowsDriver struct{}
+
+func (contactTestRowsDriver) Open(string) (driver.Conn, error) {
+	return contactTestRowsConn{}, nil
+}
+
+type contactTestRowsConn struct{}
+
+func (contactTestRowsConn) Prepare(string) (driver.Stmt, error) {
+	return nil, assert.AnError
+}
+
+func (contactTestRowsConn) Close() error {
+	return nil
+}
+
+func (contactTestRowsConn) Begin() (driver.Tx, error) {
+	return nil, assert.AnError
+}
+
+func (contactTestRowsConn) QueryContext(context.Context, string, []driver.NamedValue) (driver.Rows, error) {
+	return contactTestRows{}, nil
+}
+
+type contactTestRows struct{}
+
+func (contactTestRows) Columns() []string {
+	return []string{"id", "user_id", "name", "emails", "phone_numbers", "properties", "created_at", "updated_at"}
+}
+
+func (contactTestRows) Close() error {
+	return nil
+}
+
+func (contactTestRows) Next([]driver.Value) error {
+	return io.EOF
+}
+
+func lastContactStatement(t *testing.T, pool *contactTestConnPool) messageThreadTestStatement {
+	t.Helper()
+	require.NotEmpty(t, pool.statements)
+
+	statement := pool.statements[len(pool.statements)-1]
+	statement.query = normalizeContactSQL(statement.query)
+	return statement
+}
+
+func newContactTestRepo(t *testing.T) (ContactRepository, *contactTestConnPool) {
+	t.Helper()
+
+	pool := &contactTestConnPool{}
+	db, err := gorm.Open(
+		postgres.New(postgres.Config{
+			Conn:             pool,
+			WithoutReturning: true,
+		}),
+		&gorm.Config{
+			DisableAutomaticPing: true,
+			NowFunc: func() time.Time {
+				return time.Date(2026, 7, 19, 18, 0, 0, 0, time.UTC)
+			},
+		},
+	)
+	require.NoError(t, err)
+
+	logger := &messageThreadTestLogger{}
+	return NewGormContactRepository(logger, telemetry.NewOtelLogger("test", logger), db), pool
+}
+
+func TestGormContactRepository_Store_BatchInsertsContacts(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+	firstID := uuid.MustParse("11111111-1111-1111-1111-111111111111")
+	secondID := uuid.MustParse("22222222-2222-2222-2222-222222222222")
+
+	err := repository.Store(context.Background(), []*entities.Contact{
+		{
+			ID:           firstID,
+			UserID:       entities.UserID("user-1"),
+			Name:         "Alice",
+			Emails:       pq.StringArray{"alice@example.com"},
+			PhoneNumbers: pq.StringArray{"+18005550199"},
+			Properties:   entities.ContactProperties{"source": "phone"},
+		},
+		{
+			ID:           secondID,
+			UserID:       entities.UserID("user-1"),
+			Name:         "Bob",
+			Emails:       pq.StringArray{"bob@example.com"},
+			PhoneNumbers: pq.StringArray{"+18005550200"},
+			Properties:   entities.ContactProperties{"source": "import"},
+		},
+	})
+
+	require.NoError(t, err)
+	require.Len(t, recorder.statements, 1)
+	statement := lastContactStatement(t, recorder)
+	assert.True(t, strings.HasPrefix(statement.query, `INSERT INTO "contacts"`))
+	assert.Contains(t, statement.query, `("id","user_id","name","emails","phone_numbers","properties","created_at","updated_at")`)
+	assert.Regexp(t, regexp.MustCompile(`VALUES \(\$1,\$2,\$3,\$4,\$5,\$6,\$7,\$8\),\(\$9,\$10,\$11,\$12,\$13,\$14,\$15,\$16\)`), statement.query)
+	require.Len(t, statement.args, 16)
+	assert.Equal(t, firstID, statement.args[0])
+	assert.Equal(t, entities.UserID("user-1"), statement.args[1])
+	assert.Equal(t, "Alice", statement.args[2])
+	assert.Equal(t, pq.StringArray{"alice@example.com"}, statement.args[3])
+	assert.Equal(t, pq.StringArray{"+18005550199"}, statement.args[4])
+	assert.Equal(t, entities.ContactProperties{"source": "phone"}, statement.args[5])
+	assert.Equal(t, secondID, statement.args[8])
+	assert.Equal(t, entities.UserID("user-1"), statement.args[9])
+	assert.Equal(t, "Bob", statement.args[10])
+	assert.Equal(t, pq.StringArray{"bob@example.com"}, statement.args[11])
+	assert.Equal(t, pq.StringArray{"+18005550200"}, statement.args[12])
+	assert.Equal(t, entities.ContactProperties{"source": "import"}, statement.args[13])
+}
+
+func TestGormContactRepository_Update_SavesContact(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+	contactID := uuid.MustParse("33333333-3333-3333-3333-333333333333")
+
+	err := repository.Update(context.Background(), &entities.Contact{
+		ID:           contactID,
+		UserID:       entities.UserID("user-1"),
+		Name:         "Updated Alice",
+		Emails:       pq.StringArray{"updated@example.com"},
+		PhoneNumbers: pq.StringArray{"+18005550199"},
+		Properties:   entities.ContactProperties{"group": "friends"},
+	})
+
+	require.NoError(t, err)
+	statement := lastContactStatement(t, recorder)
+	assert.True(t, strings.HasPrefix(statement.query, `UPDATE "contacts"`))
+	assert.Contains(t, statement.query, `"user_id"=$1`)
+	assert.Contains(t, statement.query, `"name"=$2`)
+	assert.Contains(t, statement.query, `"emails"=$3`)
+	assert.Contains(t, statement.query, `"phone_numbers"=$4`)
+	assert.Contains(t, statement.query, `"properties"=$5`)
+	assert.Contains(t, statement.query, `"created_at"=$6`)
+	assert.Contains(t, statement.query, `"updated_at"=$7`)
+	assert.Contains(t, statement.query, `WHERE "id" = $8`)
+	require.Len(t, statement.args, 8)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+	assert.Equal(t, "Updated Alice", statement.args[1])
+	assert.Equal(t, pq.StringArray{"updated@example.com"}, statement.args[2])
+	assert.Equal(t, pq.StringArray{"+18005550199"}, statement.args[3])
+	assert.Equal(t, entities.ContactProperties{"group": "friends"}, statement.args[4])
+	assert.Equal(t, contactID, statement.args[7])
+}
+
+func TestGormContactRepository_Load_ScopesByUserAndContactID(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+	contactID := uuid.MustParse("44444444-4444-4444-4444-444444444444")
+
+	_, err := repository.Load(context.Background(), entities.UserID("user-1"), contactID)
+
+	require.Error(t, err)
+	assert.Equal(t, ErrCodeNotFound, stacktrace.GetCode(err))
+	statement := lastContactStatement(t, recorder)
+	assert.True(t, strings.HasPrefix(statement.query, `SELECT * FROM "contacts"`))
+	assert.Contains(t, statement.query, `WHERE user_id = $1 AND id = $2`)
+	assert.Contains(t, statement.query, `ORDER BY "contacts"."id" LIMIT $3`)
+	require.Len(t, statement.args, 3)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+	assert.Equal(t, contactID, statement.args[1])
+	assert.Equal(t, 1, statement.args[2])
+}
+
+func TestGormContactRepository_Index_FiltersByUserAndQueryAcrossContactFields(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+
+	_, err := repository.Index(context.Background(), entities.UserID("user-1"), IndexParams{
+		Query: "alice",
+		Limit: 20,
+		Skip:  40,
+	})
+
+	require.NoError(t, err)
+	statement := lastContactStatement(t, recorder)
+	assert.True(t, strings.HasPrefix(statement.query, `SELECT * FROM "contacts"`))
+	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)`)
+	assert.Contains(t, statement.query, `ORDER BY updated_at DESC LIMIT $5 OFFSET $6`)
+	require.Len(t, statement.args, 6)
+	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])
+	assert.Equal(t, 20, statement.args[4])
+	assert.Equal(t, 40, statement.args[5])
+}
+
+func TestGormContactRepository_FetchAll_ScopesByUserAndOrdersUpdatedAtAsc(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+
+	_, err := repository.FetchAll(context.Background(), entities.UserID("user-1"))
+
+	require.NoError(t, err)
+	statement := lastContactStatement(t, recorder)
+	assert.Equal(t, `SELECT * FROM "contacts" WHERE user_id = $1 ORDER BY updated_at ASC`, statement.query)
+	require.Len(t, statement.args, 1)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+}
+
+func TestGormContactRepository_Delete_ScopesByUserAndContactID(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+	contactID := uuid.MustParse("55555555-5555-5555-5555-555555555555")
+
+	err := repository.Delete(context.Background(), entities.UserID("user-1"), contactID)
+
+	require.NoError(t, err)
+	statement := lastContactStatement(t, recorder)
+	assert.Equal(t, `DELETE FROM "contacts" WHERE user_id = $1 AND id = $2`, statement.query)
+	require.Len(t, statement.args, 2)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+	assert.Equal(t, contactID, statement.args[1])
+}
+
+func TestGormContactRepository_DeleteAllForUser_ScopesByUserOnly(t *testing.T) {
+	repository, recorder := newContactTestRepo(t)
+
+	err := repository.DeleteAllForUser(context.Background(), entities.UserID("user-1"))
+
+	require.NoError(t, err)
+	statement := lastContactStatement(t, recorder)
+	assert.Equal(t, `DELETE FROM "contacts" WHERE user_id = $1`, statement.query)
+	require.Len(t, statement.args, 1)
+	assert.Equal(t, entities.UserID("user-1"), statement.args[0])
+}

From bf1a9fb8e888108d5bbbe9555f49cec09528249d Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 21:55:02 +0300
Subject: [PATCH 06/24] feat(api): add contact store/update/index requests

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/requests/contact_index.go      |  39 +++++++
 api/pkg/requests/contact_store.go      | 111 ++++++++++++++++++
 api/pkg/requests/contact_store_test.go | 156 +++++++++++++++++++++++++
 api/pkg/requests/contact_update.go     |  43 +++++++
 4 files changed, 349 insertions(+)
 create mode 100644 api/pkg/requests/contact_index.go
 create mode 100644 api/pkg/requests/contact_store.go
 create mode 100644 api/pkg/requests/contact_store_test.go
 create mode 100644 api/pkg/requests/contact_update.go

diff --git a/api/pkg/requests/contact_index.go b/api/pkg/requests/contact_index.go
new file mode 100644
index 000000000..7ed78dcc6
--- /dev/null
+++ b/api/pkg/requests/contact_index.go
@@ -0,0 +1,39 @@
+package requests
+
+import (
+	"strings"
+
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+)
+
+// ContactIndex lists contacts for a user.
+type ContactIndex struct {
+	request
+	Skip  string `json:"skip" query:"skip"`
+	Query string `json:"query" query:"query"`
+	Limit string `json:"limit" query:"limit"`
+}
+
+// Sanitize sets defaults for the list request.
+func (input *ContactIndex) Sanitize() ContactIndex {
+	input.Query = strings.TrimSpace(input.Query)
+	input.Skip = strings.TrimSpace(input.Skip)
+	input.Limit = strings.TrimSpace(input.Limit)
+
+	if input.Skip == "" {
+		input.Skip = "0"
+	}
+	if input.Limit == "" {
+		input.Limit = "20"
+	}
+	return *input
+}
+
+// ToIndexParams converts the request into repositories.IndexParams.
+func (input *ContactIndex) ToIndexParams() repositories.IndexParams {
+	return repositories.IndexParams{
+		Skip:  input.getInt(input.Skip),
+		Query: input.Query,
+		Limit: input.getInt(input.Limit),
+	}
+}
diff --git a/api/pkg/requests/contact_store.go b/api/pkg/requests/contact_store.go
new file mode 100644
index 000000000..d932602ac
--- /dev/null
+++ b/api/pkg/requests/contact_store.go
@@ -0,0 +1,111 @@
+package requests
+
+import (
+	"encoding/json"
+	"strings"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+)
+
+// ContactItem is a single contact in a create request.
+type ContactItem struct {
+	Name         string            `json:"name" example:"Alice Smith"`
+	Emails       []string          `json:"emails"`
+	PhoneNumbers []string          `json:"phone_numbers"`
+	Properties   map[string]string `json:"properties"`
+}
+
+// ContactStoreRequest creates one or many contacts.
+type ContactStoreRequest struct {
+	request
+	Contacts []ContactItem `json:"contacts"`
+}
+
+// UnmarshalJSON accepts either a JSON array of contacts or {"contacts":[...]}.
+func (input *ContactStoreRequest) UnmarshalJSON(data []byte) error {
+	trimmed := strings.TrimSpace(string(data))
+	if strings.HasPrefix(trimmed, "[") {
+		var items []ContactItem
+		if err := json.Unmarshal(data, &items); err != nil {
+			return err
+		}
+		input.Contacts = items
+		return nil
+	}
+
+	type alias ContactStoreRequest
+	var wrapper alias
+	if err := json.Unmarshal(data, &wrapper); err != nil {
+		return err
+	}
+
+	input.Contacts = wrapper.Contacts
+	return nil
+}
+
+// Sanitize trims and normalizes each contact item.
+func (input ContactStoreRequest) Sanitize() ContactStoreRequest {
+	for index := range input.Contacts {
+		input.Contacts[index] = sanitizeContactItem(input.Contacts[index])
+	}
+	return input
+}
+
+// ToContacts converts the request into persistable entities.Contact records.
+func (input *ContactStoreRequest) ToContacts(userID entities.UserID) []*entities.Contact {
+	now := time.Now().UTC()
+	contacts := make([]*entities.Contact, 0, len(input.Contacts))
+	for _, item := range input.Contacts {
+		properties := item.Properties
+		if properties == nil {
+			properties = map[string]string{}
+		}
+
+		contacts = append(contacts, &entities.Contact{
+			ID:           uuid.New(),
+			UserID:       userID,
+			Name:         item.Name,
+			Emails:       pq.StringArray(item.Emails),
+			PhoneNumbers: pq.StringArray(item.PhoneNumbers),
+			Properties:   entities.ContactProperties(properties),
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		})
+	}
+	return contacts
+}
+
+func sanitizeContactItem(item ContactItem) ContactItem {
+	item.Name = strings.TrimSpace(item.Name)
+	item.Emails = sanitizeUniqueStrings(item.Emails, func(value string) string {
+		return strings.ToLower(strings.TrimSpace(value))
+	})
+	item.PhoneNumbers = sanitizeUniqueStrings(item.PhoneNumbers, func(value string) string {
+		var base request
+		return base.sanitizeAddress(value)
+	})
+	if item.Properties == nil {
+		item.Properties = map[string]string{}
+	}
+	return item
+}
+
+func sanitizeUniqueStrings(values []string, normalize func(string) string) []string {
+	seen := map[string]struct{}{}
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		value = normalize(value)
+		if value == "" {
+			continue
+		}
+		if _, ok := seen[value]; ok {
+			continue
+		}
+		seen[value] = struct{}{}
+		result = append(result, value)
+	}
+	return result
+}
diff --git a/api/pkg/requests/contact_store_test.go b/api/pkg/requests/contact_store_test.go
new file mode 100644
index 000000000..8c65bb4e8
--- /dev/null
+++ b/api/pkg/requests/contact_store_test.go
@@ -0,0 +1,156 @@
+package requests
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestContactStoreRequest_UnmarshalArrayForm(t *testing.T) {
+	var request ContactStoreRequest
+
+	require.NoError(t, json.Unmarshal([]byte(`[{"name":"Alice","phone_numbers":["+18005550199"]}]`), &request))
+
+	require.Len(t, request.Contacts, 1)
+	assert.Equal(t, "Alice", request.Contacts[0].Name)
+	assert.Equal(t, []string{"+18005550199"}, request.Contacts[0].PhoneNumbers)
+}
+
+func TestContactStoreRequest_UnmarshalObjectForm(t *testing.T) {
+	var request ContactStoreRequest
+
+	require.NoError(t, json.Unmarshal([]byte(`{"contacts":[{"name":"Bob","phone_numbers":["+18005550100"]}]}`), &request))
+
+	require.Len(t, request.Contacts, 1)
+	assert.Equal(t, "Bob", request.Contacts[0].Name)
+	assert.Equal(t, []string{"+18005550100"}, request.Contacts[0].PhoneNumbers)
+}
+
+func TestContactStoreRequest_UnmarshalMalformedJSON(t *testing.T) {
+	var request ContactStoreRequest
+
+	err := json.Unmarshal([]byte(`{"contacts":[{"name":"Alice"`), &request)
+
+	require.Error(t, err)
+}
+
+func TestContactStoreRequest_SanitizeNormalizesAndDeduplicates(t *testing.T) {
+	request := ContactStoreRequest{Contacts: []ContactItem{{
+		Name:         "  Alice  ",
+		PhoneNumbers: []string{"18005550199", "+18005550199", " ", "+18005550100"},
+		Emails:       []string{" Alice@Example.com ", "", "alice@example.com", "B@example.com", "b@example.com"},
+		Properties:   map[string]string{"company": "Acme", "role": "CTO"},
+	}}}
+
+	request = request.Sanitize()
+
+	require.Len(t, request.Contacts, 1)
+	assert.Equal(t, "Alice", request.Contacts[0].Name)
+	assert.Equal(t, []string{"+18005550199", "+18005550100"}, request.Contacts[0].PhoneNumbers)
+	assert.Equal(t, []string{"alice@example.com", "b@example.com"}, request.Contacts[0].Emails)
+	assert.Equal(t, map[string]string{"company": "Acme", "role": "CTO"}, request.Contacts[0].Properties)
+}
+
+func TestContactStoreRequest_SanitizeInitializesNilProperties(t *testing.T) {
+	request := ContactStoreRequest{Contacts: []ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+	}}}
+
+	request = request.Sanitize()
+
+	require.Len(t, request.Contacts, 1)
+	assert.NotNil(t, request.Contacts[0].Properties)
+	assert.Empty(t, request.Contacts[0].Properties)
+}
+
+func TestContactStoreRequest_ToContactsPreservesPropertiesAndOwnership(t *testing.T) {
+	request := ContactStoreRequest{Contacts: []ContactItem{{
+		Name:         "Alice",
+		Emails:       []string{"alice@example.com"},
+		PhoneNumbers: []string{"+18005550199"},
+		Properties:   map[string]string{"company": "Acme"},
+	}}}.Sanitize()
+
+	contacts := request.ToContacts(entities.UserID("user-1"))
+
+	require.Len(t, contacts, 1)
+	assert.NotZero(t, contacts[0].ID)
+	assert.Equal(t, entities.UserID("user-1"), contacts[0].UserID)
+	assert.Equal(t, "Alice", contacts[0].Name)
+	assert.Equal(t, []string{"alice@example.com"}, []string(contacts[0].Emails))
+	assert.Equal(t, []string{"+18005550199"}, []string(contacts[0].PhoneNumbers))
+	assert.Equal(t, entities.ContactProperties{"company": "Acme"}, contacts[0].Properties)
+	assert.False(t, contacts[0].CreatedAt.IsZero())
+	assert.False(t, contacts[0].UpdatedAt.IsZero())
+	assert.True(t, contacts[0].CreatedAt.Equal(contacts[0].UpdatedAt))
+}
+
+func TestContactUpdateRequest_SanitizeAndApplyTo(t *testing.T) {
+	request := ContactUpdateRequest{
+		Name:         "  Alice  ",
+		Emails:       []string{" Alice@Example.com ", "", "alice@example.com"},
+		PhoneNumbers: []string{"18005550199", "+18005550199"},
+		Properties:   map[string]string{"nickname": "Al"},
+	}.Sanitize()
+
+	contact := &entities.Contact{
+		ID:           uuid.MustParse("32343a19-da5e-4b1b-a767-3298a73703cb"),
+		UserID:       entities.UserID("user-1"),
+		Name:         "Before",
+		Emails:       nil,
+		PhoneNumbers: nil,
+		Properties:   entities.ContactProperties{"old": "value"},
+		CreatedAt:    time.Unix(1, 0).UTC(),
+		UpdatedAt:    time.Unix(2, 0).UTC(),
+	}
+
+	request.ApplyTo(contact)
+
+	assert.Equal(t, "Alice", contact.Name)
+	assert.Equal(t, []string{"alice@example.com"}, []string(contact.Emails))
+	assert.Equal(t, []string{"+18005550199"}, []string(contact.PhoneNumbers))
+	assert.Equal(t, entities.ContactProperties{"nickname": "Al"}, contact.Properties)
+	assert.Equal(t, time.Unix(1, 0).UTC(), contact.CreatedAt)
+	assert.True(t, contact.UpdatedAt.After(time.Unix(2, 0).UTC()))
+}
+
+func TestContactUpdateRequest_InitializesNilProperties(t *testing.T) {
+	request := ContactUpdateRequest{Name: "Alice", PhoneNumbers: []string{"+18005550199"}}.Sanitize()
+
+	assert.NotNil(t, request.Properties)
+	assert.Empty(t, request.Properties)
+}
+
+func TestContactIndex_SanitizeUsesDefaultsAndToIndexParams(t *testing.T) {
+	request := ContactIndex{}
+
+	sanitized := request.Sanitize()
+	params := sanitized.ToIndexParams()
+
+	assert.Equal(t, "0", sanitized.Skip)
+	assert.Equal(t, "20", sanitized.Limit)
+	assert.Equal(t, "", sanitized.Query)
+	assert.Equal(t, 0, params.Skip)
+	assert.Equal(t, 20, params.Limit)
+	assert.Equal(t, "", params.Query)
+}
+
+func TestContactIndex_SanitizeTrimsAndConverts(t *testing.T) {
+	request := ContactIndex{Skip: " 15 ", Limit: " 50 ", Query: " alice "}
+
+	sanitized := request.Sanitize()
+	params := sanitized.ToIndexParams()
+
+	assert.Equal(t, "15", sanitized.Skip)
+	assert.Equal(t, "50", sanitized.Limit)
+	assert.Equal(t, "alice", sanitized.Query)
+	assert.Equal(t, 15, params.Skip)
+	assert.Equal(t, 50, params.Limit)
+	assert.Equal(t, "alice", params.Query)
+}
diff --git a/api/pkg/requests/contact_update.go b/api/pkg/requests/contact_update.go
new file mode 100644
index 000000000..67772669d
--- /dev/null
+++ b/api/pkg/requests/contact_update.go
@@ -0,0 +1,43 @@
+package requests
+
+import (
+	"strings"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/lib/pq"
+)
+
+// ContactUpdateRequest updates an existing contact.
+type ContactUpdateRequest struct {
+	request
+	Name         string            `json:"name" example:"Alice Smith"`
+	Emails       []string          `json:"emails"`
+	PhoneNumbers []string          `json:"phone_numbers"`
+	Properties   map[string]string `json:"properties"`
+}
+
+// Sanitize trims and normalizes the update request.
+func (input ContactUpdateRequest) Sanitize() ContactUpdateRequest {
+	input.Name = strings.TrimSpace(input.Name)
+	input.Emails = sanitizeUniqueStrings(input.Emails, func(value string) string {
+		return strings.ToLower(strings.TrimSpace(value))
+	})
+	input.PhoneNumbers = sanitizeUniqueStrings(input.PhoneNumbers, func(value string) string {
+		var base request
+		return base.sanitizeAddress(value)
+	})
+	if input.Properties == nil {
+		input.Properties = map[string]string{}
+	}
+	return input
+}
+
+// ApplyTo mutates an existing contact with the update values.
+func (input *ContactUpdateRequest) ApplyTo(contact *entities.Contact) {
+	contact.Name = input.Name
+	contact.Emails = pq.StringArray(input.Emails)
+	contact.PhoneNumbers = pq.StringArray(input.PhoneNumbers)
+	contact.Properties = entities.ContactProperties(input.Properties)
+	contact.UpdatedAt = time.Now().UTC()
+}

From ad95d55f442a868ff2689a5795f094fd924bac86 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 21:59:36 +0300
Subject: [PATCH 07/24] fix(api): keep contact sanitization ordered

Move sanitizeUniqueStrings into the shared requests helper.
Preserve first-seen ordering after normalization.
Add a direct ToContacts nil-properties regression test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/requests/contact_store.go      | 17 -----------------
 api/pkg/requests/contact_store_test.go | 13 +++++++++++++
 api/pkg/requests/request.go            | 18 ++++++++++++++++++
 3 files changed, 31 insertions(+), 17 deletions(-)

diff --git a/api/pkg/requests/contact_store.go b/api/pkg/requests/contact_store.go
index d932602ac..78025fbd6 100644
--- a/api/pkg/requests/contact_store.go
+++ b/api/pkg/requests/contact_store.go
@@ -92,20 +92,3 @@ func sanitizeContactItem(item ContactItem) ContactItem {
 	}
 	return item
 }
-
-func sanitizeUniqueStrings(values []string, normalize func(string) string) []string {
-	seen := map[string]struct{}{}
-	result := make([]string, 0, len(values))
-	for _, value := range values {
-		value = normalize(value)
-		if value == "" {
-			continue
-		}
-		if _, ok := seen[value]; ok {
-			continue
-		}
-		seen[value] = struct{}{}
-		result = append(result, value)
-	}
-	return result
-}
diff --git a/api/pkg/requests/contact_store_test.go b/api/pkg/requests/contact_store_test.go
index 8c65bb4e8..2efd67b91 100644
--- a/api/pkg/requests/contact_store_test.go
+++ b/api/pkg/requests/contact_store_test.go
@@ -91,6 +91,19 @@ func TestContactStoreRequest_ToContactsPreservesPropertiesAndOwnership(t *testin
 	assert.True(t, contacts[0].CreatedAt.Equal(contacts[0].UpdatedAt))
 }
 
+func TestContactStoreRequest_ToContactsInitializesNilProperties(t *testing.T) {
+	request := ContactStoreRequest{Contacts: []ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+	}}}
+
+	contacts := request.ToContacts(entities.UserID("user-1"))
+
+	require.Len(t, contacts, 1)
+	assert.NotNil(t, contacts[0].Properties)
+	assert.Empty(t, contacts[0].Properties)
+}
+
 func TestContactUpdateRequest_SanitizeAndApplyTo(t *testing.T) {
 	request := ContactUpdateRequest{
 		Name:         "  Alice  ",
diff --git a/api/pkg/requests/request.go b/api/pkg/requests/request.go
index 1db278614..af2066835 100644
--- a/api/pkg/requests/request.go
+++ b/api/pkg/requests/request.go
@@ -120,6 +120,24 @@ func (input *request) removeEmptyStrings(values []string) []string {
 	return result
 }
 
+func sanitizeUniqueStrings(values []string, normalize func(string) string) []string {
+	seen := map[string]struct{}{}
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		value = normalize(value)
+		if value == "" {
+			continue
+		}
+		if _, ok := seen[value]; ok {
+			continue
+		}
+		seen[value] = struct{}{}
+		result = append(result, value)
+	}
+
+	return result
+}
+
 func (input *request) sanitizeMessageID(value string) string {
 	id := strings.Builder{}
 	for _, char := range value {

From 1b75db2b46cfb4f14edaf7284840fd5c52c95407 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 22:10:16 +0300
Subject: [PATCH 08/24] feat(api): add contact validator

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../validators/contact_handler_validator.go   | 349 +++++++++++++++++
 .../contact_handler_validator_test.go         | 355 ++++++++++++++++++
 2 files changed, 704 insertions(+)
 create mode 100644 api/pkg/validators/contact_handler_validator.go
 create mode 100644 api/pkg/validators/contact_handler_validator_test.go

diff --git a/api/pkg/validators/contact_handler_validator.go b/api/pkg/validators/contact_handler_validator.go
new file mode 100644
index 000000000..4e8f6b978
--- /dev/null
+++ b/api/pkg/validators/contact_handler_validator.go
@@ -0,0 +1,349 @@
+package validators
+
+import (
+	"bytes"
+	"context"
+	"encoding/csv"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/mail"
+	"net/url"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/requests"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/nyaruka/phonenumbers"
+	"github.com/thedevsaddam/govalidator"
+)
+
+const (
+	maxContactBatch          = 1000
+	maxContactUploadBytes    = 500 * 1024
+	contactUploadDocumentKey = "document"
+	contactUploadContactsKey = "contacts"
+	contactCSVColumnName     = "Name"
+	contactCSVColumnEmails   = "Emails"
+	contactCSVColumnPhones   = "PhoneNumbers"
+	contactCSVContentType    = "text/csv"
+	contactCSVContentTypeAlt = "application/csv"
+)
+
+// ContactHandlerValidator validates models used in handlers.ContactHandler
+type ContactHandlerValidator struct {
+	validator
+	logger telemetry.Logger
+	tracer telemetry.Tracer
+}
+
+// NewContactHandlerValidator creates a new handlers.ContactHandler validator
+func NewContactHandlerValidator(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+) (v *ContactHandlerValidator) {
+	return &ContactHandlerValidator{
+		logger: logger.WithService(fmt.Sprintf("%T", v)),
+		tracer: tracer,
+	}
+}
+
+// ValidateStore validates a contact create request.
+func (validator *ContactHandlerValidator) ValidateStore(_ context.Context, request requests.ContactStoreRequest) url.Values {
+	result := url.Values{}
+
+	if len(request.Contacts) == 0 {
+		result.Add(contactUploadContactsKey, "You must provide at least one contact.")
+		return result
+	}
+
+	if len(request.Contacts) > maxContactBatch {
+		result.Add(contactUploadContactsKey, fmt.Sprintf("You cannot create more than %d contacts in one request.", maxContactBatch))
+		return result
+	}
+
+	for index, item := range request.Contacts {
+		validator.validateItem(result, contactUploadContactsKey, "Contact", index+1, item)
+	}
+
+	return result
+}
+
+// ValidateUpdate validates a contact update request.
+func (validator *ContactHandlerValidator) ValidateUpdate(_ context.Context, request requests.ContactUpdateRequest) url.Values {
+	result := url.Values{}
+	validator.validateItem(result, contactUploadContactsKey, "Contact", 1, requests.ContactItem{
+		Name:         request.Name,
+		Emails:       request.Emails,
+		PhoneNumbers: request.PhoneNumbers,
+		Properties:   request.Properties,
+	})
+	return result
+}
+
+// ValidateIndex validates a contact index request.
+func (validator *ContactHandlerValidator) ValidateIndex(_ context.Context, request requests.ContactIndex) url.Values {
+	result := govalidator.New(govalidator.Options{
+		Data: &request,
+		Rules: govalidator.MapData{
+			"limit": []string{"required", "numeric"},
+			"skip":  []string{"required", "numeric"},
+			"query": []string{"max:100"},
+		},
+	}).ValidateStruct()
+
+	if limit, err := strconv.Atoi(request.Limit); request.Limit != "" && err == nil {
+		if limit < 1 || limit > 100 {
+			result.Add("limit", "The limit must be between 1 and 100.")
+		}
+	}
+
+	if skip, err := strconv.Atoi(request.Skip); request.Skip != "" && err == nil {
+		if skip < 0 {
+			result.Add("skip", "The skip must be greater than or equal to 0.")
+		}
+	}
+
+	return result
+}
+
+// ValidateUpload parses and validates a CSV contacts upload.
+func (validator *ContactHandlerValidator) ValidateUpload(ctx context.Context, userID entities.UserID, header *multipart.FileHeader) ([]requests.ContactItem, url.Values) {
+	_, span, ctxLogger := validator.tracer.StartWithLogger(ctx, validator.logger)
+	defer span.End()
+
+	result := url.Values{}
+	if header == nil {
+		result.Add(contactUploadDocumentKey, "The CSV file is required.")
+		return nil, result
+	}
+
+	if !isContactCSVFile(header) {
+		ctxLogger.Error(stacktrace.NewErrorf("cannot parse file [%s] for user [%s] with content type [%s]", header.Filename, userID, header.Header.Get("Content-Type")))
+		result.Add(contactUploadDocumentKey, fmt.Sprintf("The file [%s] is not a valid CSV file. Only CSV files are supported.", header.Filename))
+		return nil, result
+	}
+
+	content, errors := validator.parseContactUploadBytes(ctxLogger, userID, header)
+	if len(errors) != 0 {
+		return nil, errors
+	}
+
+	rows, errors := validator.parseContactCSV(ctxLogger, userID, header.Filename, content)
+	if len(errors) != 0 {
+		return nil, errors
+	}
+
+	if len(rows) > maxContactBatch {
+		result.Add(contactUploadDocumentKey, fmt.Sprintf("The uploaded file must contain no more than %d records.", maxContactBatch))
+		return nil, result
+	}
+
+	items := make([]requests.ContactItem, 0, len(rows))
+	for _, row := range rows {
+		item := requests.ContactItem{
+			Name:         strings.TrimSpace(row.values[contactCSVColumnName]),
+			Emails:       splitContactMultiValue(row.values[contactCSVColumnEmails]),
+			PhoneNumbers: splitContactMultiValue(row.values[contactCSVColumnPhones]),
+		}
+		items = append(items, item)
+		validator.validateItem(result, contactUploadDocumentKey, "Row", row.number, item)
+	}
+
+	if len(items) == 0 {
+		result.Add(contactUploadDocumentKey, "The uploaded file must contain at least one contact.")
+	}
+
+	return items, result
+}
+
+func (validator *ContactHandlerValidator) validateItem(result url.Values, key string, label string, index int, item requests.ContactItem) {
+	prefix := fmt.Sprintf("%s [%d]", label, index)
+
+	if strings.TrimSpace(item.Name) == "" {
+		result.Add(key, fmt.Sprintf("%s: The name is required.", prefix))
+	}
+
+	if !hasNonEmptyValue(item.PhoneNumbers) {
+		result.Add(key, fmt.Sprintf("%s: At least one phone number is required.", prefix))
+	}
+
+	for _, number := range item.PhoneNumbers {
+		cleanNumber := strings.TrimSpace(number)
+		if cleanNumber == "" {
+			result.Add(key, fmt.Sprintf("%s: The phone number is required.", prefix))
+			continue
+		}
+
+		parsed, err := phonenumbers.Parse(cleanNumber, phonenumbers.UNKNOWN_REGION)
+		if err != nil || !phonenumbers.IsValidNumber(parsed) {
+			result.Add(key, fmt.Sprintf("%s: The phone number [%s] is not a valid E.164 phone number.", prefix, cleanNumber))
+		}
+	}
+
+	for _, email := range item.Emails {
+		cleanEmail := strings.TrimSpace(email)
+		if cleanEmail == "" {
+			result.Add(key, fmt.Sprintf("%s: The email is not a valid email address.", prefix))
+			continue
+		}
+
+		address, err := mail.ParseAddress(cleanEmail)
+		if err != nil || address.Address != cleanEmail {
+			result.Add(key, fmt.Sprintf("%s: The email [%s] is not a valid email address.", prefix, cleanEmail))
+		}
+	}
+}
+
+func (validator *ContactHandlerValidator) parseContactUploadBytes(ctxLogger telemetry.Logger, userID entities.UserID, header *multipart.FileHeader) ([]byte, url.Values) {
+	result := url.Values{}
+
+	if header.Size > maxContactUploadBytes {
+		result.Add(contactUploadDocumentKey, "The CSV file must be less than or equal to 500 KB.")
+		return nil, result
+	}
+
+	file, err := header.Open()
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot open file [%s] for reading for user [%s]", header.Filename, userID))
+		result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot open the uploaded file [%s].", header.Filename))
+		return nil, result
+	}
+	defer func() {
+		if closeErr := file.Close(); closeErr != nil {
+			ctxLogger.Error(stacktrace.Propagatef(closeErr, "cannot close file [%s] for user [%s]", header.Filename, userID))
+		}
+	}()
+
+	content, err := io.ReadAll(io.LimitReader(file, maxContactUploadBytes+1))
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot read file [%s] for user [%s]", header.Filename, userID))
+		result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot read the uploaded file [%s].", header.Filename))
+		return nil, result
+	}
+
+	if len(content) > maxContactUploadBytes {
+		result.Add(contactUploadDocumentKey, "The CSV file must be less than or equal to 500 KB.")
+		return nil, result
+	}
+
+	return content, result
+}
+
+type contactCSVRow struct {
+	number int
+	values map[string]string
+}
+
+func (validator *ContactHandlerValidator) parseContactCSV(ctxLogger telemetry.Logger, userID entities.UserID, filename string, content []byte) ([]contactCSVRow, url.Values) {
+	result := url.Values{}
+	reader := csv.NewReader(bytes.NewReader(content))
+	reader.TrimLeadingSpace = true
+
+	headers, err := reader.Read()
+	if err == io.EOF {
+		result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. The file is empty.", filename))
+		return nil, result
+	}
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot read CSV header from file [%s] for user [%s]", filename, userID))
+		result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. Use the official httpSMS contacts template.", filename))
+		return nil, result
+	}
+
+	columnIndexes, ok := contactCSVColumnIndexes(headers)
+	if !ok {
+		result.Add(contactUploadDocumentKey, "The uploaded CSV file must contain the columns [Name, Emails, PhoneNumbers].")
+		return nil, result
+	}
+
+	reader.FieldsPerRecord = len(headers)
+
+	var rows []contactCSVRow
+	for rowNumber := 2; ; rowNumber++ {
+		record, readErr := reader.Read()
+		if readErr == io.EOF {
+			break
+		}
+		if readErr != nil {
+			ctxLogger.Error(stacktrace.Propagatef(readErr, "cannot read CSV row [%d] from file [%s] for user [%s]", rowNumber, filename, userID))
+			result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. Use the official httpSMS contacts template.", filename))
+			return nil, result
+		}
+
+		row := contactCSVRow{
+			number: rowNumber,
+			values: map[string]string{
+				contactCSVColumnName:   record[columnIndexes[contactCSVColumnName]],
+				contactCSVColumnEmails: record[columnIndexes[contactCSVColumnEmails]],
+				contactCSVColumnPhones: record[columnIndexes[contactCSVColumnPhones]],
+			},
+		}
+		rows = append(rows, row)
+		if len(rows) > maxContactBatch {
+			return rows, result
+		}
+	}
+
+	return rows, result
+}
+
+func contactCSVColumnIndexes(headers []string) (map[string]int, bool) {
+	required := []string{contactCSVColumnName, contactCSVColumnEmails, contactCSVColumnPhones}
+	indexes := map[string]int{}
+	for index, header := range headers {
+		indexes[strings.TrimSpace(header)] = index
+	}
+
+	for _, column := range required {
+		if _, ok := indexes[column]; !ok {
+			return nil, false
+		}
+	}
+
+	return indexes, true
+}
+
+func isContactCSVFile(header *multipart.FileHeader) bool {
+	if strings.ToLower(filepath.Ext(header.Filename)) != ".csv" {
+		return false
+	}
+
+	contentType := strings.ToLower(strings.TrimSpace(header.Header.Get("Content-Type")))
+	if index := strings.Index(contentType, ";"); index >= 0 {
+		contentType = strings.TrimSpace(contentType[:index])
+	}
+
+	return contentType == contactCSVContentType ||
+		contentType == contactCSVContentTypeAlt
+}
+
+func splitContactMultiValue(value string) []string {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+
+	var result []string
+	for _, item := range strings.FieldsFunc(value, func(r rune) bool {
+		return r == ',' || r == ';'
+	}) {
+		item = strings.TrimSpace(item)
+		if item != "" {
+			result = append(result, item)
+		}
+	}
+
+	return result
+}
+
+func hasNonEmptyValue(values []string) bool {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return true
+		}
+	}
+	return false
+}
diff --git a/api/pkg/validators/contact_handler_validator_test.go b/api/pkg/validators/contact_handler_validator_test.go
new file mode 100644
index 000000000..6ed247f2f
--- /dev/null
+++ b/api/pkg/validators/contact_handler_validator_test.go
@@ -0,0 +1,355 @@
+package validators
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"net/textproto"
+	"strings"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/requests"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel/trace"
+)
+
+func newContactValidator() *ContactHandlerValidator {
+	return &ContactHandlerValidator{}
+}
+
+func newContactUploadValidator() *ContactHandlerValidator {
+	logger := &contactValidatorNoopLogger{}
+	return NewContactHandlerValidator(logger, telemetry.NewOtelLogger("test", logger))
+}
+
+func TestContactValidator_ValidateStore_ValidOneAndMany(t *testing.T) {
+	validator := newContactValidator()
+
+	tests := []struct {
+		name    string
+		request requests.ContactStoreRequest
+	}{
+		{
+			name: "one contact",
+			request: requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+				Name:         "Alice",
+				PhoneNumbers: []string{"+18005550199"},
+				Emails:       []string{"alice@example.com"},
+			}}},
+		},
+		{
+			name: "many contacts",
+			request: requests.ContactStoreRequest{Contacts: []requests.ContactItem{
+				{
+					Name:         "Alice",
+					PhoneNumbers: []string{"+18005550199", "+18005550100"},
+					Emails:       []string{"alice@example.com", "alice.work@example.com"},
+				},
+				{
+					Name:         "Bob",
+					PhoneNumbers: []string{"+14155552671"},
+				},
+			}},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			errs := validator.ValidateStore(context.Background(), tt.request)
+
+			assert.Empty(t, errs)
+		})
+	}
+}
+
+func TestContactValidator_ValidateStore_MissingName(t *testing.T) {
+	validator := newContactValidator()
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		PhoneNumbers: []string{"+18005550199"},
+	}}})
+
+	require.NotEmpty(t, errs.Get("contacts"))
+	assert.Contains(t, errs["contacts"][0], "Contact [1]")
+	assert.Contains(t, errs["contacts"][0], "name")
+}
+
+func TestContactValidator_ValidateStore_NoPhoneNumber(t *testing.T) {
+	validator := newContactValidator()
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name: "Alice",
+	}}})
+
+	require.NotEmpty(t, errs.Get("contacts"))
+	assert.Contains(t, errs["contacts"][0], "Contact [1]")
+	assert.Contains(t, errs["contacts"][0], "phone number")
+}
+
+func TestContactValidator_ValidateStore_EmptyBatch(t *testing.T) {
+	validator := newContactValidator()
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{})
+
+	require.NotEmpty(t, errs.Get("contacts"))
+	assert.Contains(t, errs["contacts"][0], "at least one contact")
+}
+
+func TestContactValidator_ValidateStore_InvalidPhoneNumber(t *testing.T) {
+	validator := newContactValidator()
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"not-a-number"},
+	}}})
+
+	require.NotEmpty(t, errs.Get("contacts"))
+	assert.Contains(t, errs["contacts"][0], "Contact [1]")
+	assert.Contains(t, errs["contacts"][0], "not-a-number")
+}
+
+func TestContactValidator_ValidateStore_InvalidEmail(t *testing.T) {
+	validator := newContactValidator()
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+		Emails:       []string{"not-an-email"},
+	}}})
+
+	require.NotEmpty(t, errs.Get("contacts"))
+	assert.Contains(t, errs["contacts"][0], "Contact [1]")
+	assert.Contains(t, errs["contacts"][0], "not-an-email")
+}
+
+func TestContactValidator_ValidateStore_RejectsEmptyPhoneAndEmailElements(t *testing.T) {
+	validator := newContactValidator()
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199", " "},
+		Emails:       []string{" "},
+	}}})
+
+	contactsErrors := strings.Join(errs["contacts"], "\n")
+	assert.Contains(t, contactsErrors, "phone number")
+	assert.Contains(t, contactsErrors, "email")
+}
+
+func TestContactValidator_ValidateStore_RejectsMoreThan1000Contacts(t *testing.T) {
+	validator := newContactValidator()
+	contacts := make([]requests.ContactItem, 1001)
+	for index := range contacts {
+		contacts[index] = requests.ContactItem{Name: "Alice", PhoneNumbers: []string{"+18005550199"}}
+	}
+
+	errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: contacts})
+
+	require.NotEmpty(t, errs.Get("contacts"))
+	assert.Contains(t, errs["contacts"][0], "1000")
+}
+
+func TestContactValidator_ValidateUpdate_ValidAndInvalid(t *testing.T) {
+	validator := newContactValidator()
+
+	validErrs := validator.ValidateUpdate(context.Background(), requests.ContactUpdateRequest{
+		Name:         "Alice",
+		PhoneNumbers: []string{"+18005550199"},
+		Emails:       []string{"alice@example.com"},
+	})
+	assert.Empty(t, validErrs)
+
+	invalidErrs := validator.ValidateUpdate(context.Background(), requests.ContactUpdateRequest{
+		Name:         "",
+		PhoneNumbers: []string{"not-a-number"},
+		Emails:       []string{"not-an-email"},
+	})
+	assert.NotEmpty(t, invalidErrs.Get("contacts"))
+}
+
+func TestContactValidator_ValidateIndex_Bounds(t *testing.T) {
+	validator := newContactValidator()
+
+	validErrs := validator.ValidateIndex(context.Background(), requests.ContactIndex{Skip: "0", Limit: "100", Query: strings.Repeat("a", 100)})
+	assert.Empty(t, validErrs)
+
+	tests := []struct {
+		name    string
+		request requests.ContactIndex
+		key     string
+	}{
+		{name: "limit too low", request: requests.ContactIndex{Skip: "0", Limit: "0"}, key: "limit"},
+		{name: "limit too high", request: requests.ContactIndex{Skip: "0", Limit: "101"}, key: "limit"},
+		{name: "skip negative", request: requests.ContactIndex{Skip: "-1", Limit: "20"}, key: "skip"},
+		{name: "query too long", request: requests.ContactIndex{Skip: "0", Limit: "20", Query: strings.Repeat("a", 101)}, key: "query"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			errs := validator.ValidateIndex(context.Background(), tt.request)
+
+			assert.NotEmpty(t, errs.Get(tt.key))
+		})
+	}
+}
+
+func TestContactValidator_ValidateUpload_ParsesValidCSVWithQuotedMultiValueCells(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join([]string{
+		"Name,Emails,PhoneNumbers",
+		`Alice,"alice@example.com,alice.work@example.com","+18005550199,+18005550100"`,
+		`Bob,bob@example.com;bob.work@example.com,+14155552671;+14155552672`,
+	}, "\n"))
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	require.Empty(t, errs)
+	require.Len(t, items, 2)
+	assert.Equal(t, "Alice", items[0].Name)
+	assert.Equal(t, []string{"alice@example.com", "alice.work@example.com"}, items[0].Emails)
+	assert.Equal(t, []string{"+18005550199", "+18005550100"}, items[0].PhoneNumbers)
+	assert.Equal(t, "Bob", items[1].Name)
+	assert.Equal(t, []string{"bob@example.com", "bob.work@example.com"}, items[1].Emails)
+	assert.Equal(t, []string{"+14155552671", "+14155552672"}, items[1].PhoneNumbers)
+}
+
+func TestContactValidator_ValidateUpload_RejectsNonCSVExtensionAndMIME(t *testing.T) {
+	validator := newContactUploadValidator()
+
+	tests := []struct {
+		name        string
+		filename    string
+		contentType string
+	}{
+		{name: "xlsx extension", filename: "contacts.xlsx", contentType: "text/csv"},
+		{name: "xlsx mime", filename: "contacts.csv", contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			header := multipartFileHeader(t, tt.filename, tt.contentType, "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199")
+
+			items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+			assert.Nil(t, items)
+			assert.NotEmpty(t, errs.Get("document"))
+		})
+	}
+}
+
+func TestContactValidator_ValidateUpload_RejectsOversizedFile(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Repeat("a", 500*1024+1))
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	assert.Nil(t, items)
+	require.NotEmpty(t, errs.Get("document"))
+	assert.Contains(t, errs["document"][0], "500 KB")
+}
+
+func TestContactValidator_ValidateUpload_RejectsMalformedCSV(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", "Name,Emails,PhoneNumbers\nAlice,\"alice@example.com,+18005550199")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	assert.Nil(t, items)
+	require.NotEmpty(t, errs.Get("document"))
+	assert.Contains(t, errs["document"][0], "Cannot parse")
+}
+
+func TestContactValidator_ValidateUpload_RejectsMissingRequiredColumns(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", "Name,Emails\nAlice,alice@example.com")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	assert.Nil(t, items)
+	require.NotEmpty(t, errs.Get("document"))
+	assert.Contains(t, errs["document"][0], "Name, Emails, PhoneNumbers")
+}
+
+func TestContactValidator_ValidateUpload_RejectsMoreThan1000Rows(t *testing.T) {
+	validator := newContactUploadValidator()
+	rows := []string{"Name,Emails,PhoneNumbers"}
+	for range 1001 {
+		rows = append(rows, "Alice,alice@example.com,+18005550199")
+	}
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join(rows, "\n"))
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	assert.Nil(t, items)
+	require.NotEmpty(t, errs.Get("document"))
+	assert.Contains(t, errs["document"][0], "1000")
+}
+
+func TestContactValidator_ValidateUpload_ReturnsRowIndexedValidationErrors(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join([]string{
+		"Name,Emails,PhoneNumbers",
+		",alice@example.com,+18005550199",
+		"Alice,,",
+		"Bob,not-an-email,not-a-number",
+	}, "\n"))
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	require.Len(t, items, 3)
+	documentErrors := strings.Join(errs["document"], "\n")
+	assert.Contains(t, documentErrors, "Row [2]")
+	assert.Contains(t, documentErrors, "Row [3]")
+	assert.Contains(t, documentErrors, "Row [4]")
+	assert.Contains(t, documentErrors, "not-an-email")
+	assert.Contains(t, documentErrors, "not-a-number")
+}
+
+func multipartFileHeader(t *testing.T, filename string, contentType string, content string) *multipart.FileHeader {
+	t.Helper()
+
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	header := textproto.MIMEHeader{}
+	header.Set("Content-Disposition", fmt.Sprintf(`form-data; name="document"; filename="%s"`, filename))
+	header.Set("Content-Type", contentType)
+
+	part, err := writer.CreatePart(header)
+	require.NoError(t, err)
+	_, err = part.Write([]byte(content))
+	require.NoError(t, err)
+	require.NoError(t, writer.Close())
+
+	request := httptest.NewRequest(http.MethodPost, "/", &body)
+	request.Header.Set("Content-Type", writer.FormDataContentType())
+	require.NoError(t, request.ParseMultipartForm(int64(body.Len()+1024)))
+	files := request.MultipartForm.File["document"]
+	require.Len(t, files, 1)
+
+	return files[0]
+}
+
+type contactValidatorNoopLogger struct{}
+
+var _ telemetry.Logger = (*contactValidatorNoopLogger)(nil)
+
+func (logger *contactValidatorNoopLogger) Error(_ error)                         {}
+func (logger *contactValidatorNoopLogger) WithService(_ string) telemetry.Logger { return logger }
+
+func (logger *contactValidatorNoopLogger) WithString(_, _ string) telemetry.Logger { return logger }
+
+func (logger *contactValidatorNoopLogger) WithSpan(_ trace.SpanContext) telemetry.Logger {
+	return logger
+}
+func (logger *contactValidatorNoopLogger) Trace(_ string)                    {}
+func (logger *contactValidatorNoopLogger) Info(_ string)                     {}
+func (logger *contactValidatorNoopLogger) Warn(_ error)                      {}
+func (logger *contactValidatorNoopLogger) Debug(_ string)                    {}
+func (logger *contactValidatorNoopLogger) Fatal(_ error)                     {}
+func (logger *contactValidatorNoopLogger) Printf(_ string, _ ...interface{}) {}

From ceb85aa94d7b13df2296db22cf4ab56d995f02ef Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 22:19:05 +0300
Subject: [PATCH 09/24] fix(api): accept common CSV MIME types

Allow .csv extension only; accept common browser MIME fallbacks for uploads.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../validators/contact_handler_validator.go   |  9 ++-
 .../contact_handler_validator_test.go         | 55 +++++++++++++++++++
 2 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/api/pkg/validators/contact_handler_validator.go b/api/pkg/validators/contact_handler_validator.go
index 4e8f6b978..2ca5319b9 100644
--- a/api/pkg/validators/contact_handler_validator.go
+++ b/api/pkg/validators/contact_handler_validator.go
@@ -31,6 +31,8 @@ const (
 	contactCSVColumnPhones   = "PhoneNumbers"
 	contactCSVContentType    = "text/csv"
 	contactCSVContentTypeAlt = "application/csv"
+	contactCSVContentTypeBin = "application/octet-stream"
+	contactCSVContentTypeXls = "application/vnd.ms-excel"
 )
 
 // ContactHandlerValidator validates models used in handlers.ContactHandler
@@ -317,8 +319,11 @@ func isContactCSVFile(header *multipart.FileHeader) bool {
 		contentType = strings.TrimSpace(contentType[:index])
 	}
 
-	return contentType == contactCSVContentType ||
-		contentType == contactCSVContentTypeAlt
+	return contentType == "" ||
+		contentType == contactCSVContentType ||
+		contentType == contactCSVContentTypeAlt ||
+		contentType == contactCSVContentTypeBin ||
+		contentType == contactCSVContentTypeXls
 }
 
 func splitContactMultiValue(value string) []string {
diff --git a/api/pkg/validators/contact_handler_validator_test.go b/api/pkg/validators/contact_handler_validator_test.go
index 6ed247f2f..84570881f 100644
--- a/api/pkg/validators/contact_handler_validator_test.go
+++ b/api/pkg/validators/contact_handler_validator_test.go
@@ -243,6 +243,61 @@ func TestContactValidator_ValidateUpload_RejectsNonCSVExtensionAndMIME(t *testin
 	}
 }
 
+func TestContactValidator_ValidateUpload_AcceptsCSVWithOctetStreamMIME(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "application/octet-stream", "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	require.Empty(t, errs)
+	require.Len(t, items, 1)
+	assert.Equal(t, "Alice", items[0].Name)
+}
+
+func TestContactValidator_ValidateUpload_AcceptsCSVWithVndMsExcelMIME(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "application/vnd.ms-excel", "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	require.Empty(t, errs)
+	require.Len(t, items, 1)
+	assert.Equal(t, "Alice", items[0].Name)
+}
+
+func TestContactValidator_ValidateUpload_AcceptsCSVWithEmptyMIME(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "", "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	require.Empty(t, errs)
+	require.Len(t, items, 1)
+	assert.Equal(t, "Alice", items[0].Name)
+}
+
+func TestContactValidator_ValidateUpload_RejectsXlsxDespiteSpreadsheetMIME(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.xlsx", "application/vnd.ms-excel", "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	assert.Nil(t, items)
+	require.NotEmpty(t, errs.Get("document"))
+	assert.Contains(t, errs["document"][0], "not a valid CSV file")
+}
+
+func TestContactValidator_ValidateUpload_RejectsCSVWithUnrelatedMIME(t *testing.T) {
+	validator := newContactUploadValidator()
+	header := multipartFileHeader(t, "contacts.csv", "image/png", "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199")
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	assert.Nil(t, items)
+	require.NotEmpty(t, errs.Get("document"))
+	assert.Contains(t, errs["document"][0], "not a valid CSV file")
+}
+
 func TestContactValidator_ValidateUpload_RejectsOversizedFile(t *testing.T) {
 	validator := newContactUploadValidator()
 	header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Repeat("a", 500*1024+1))

From 0dd49adb46276da525f9003bd5e817106fb0de14 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 22:30:01 +0300
Subject: [PATCH 10/24] feat(api): add ContactService with cached contact-map
 resolution

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/services/contact_service.go      | 179 +++++++
 api/pkg/services/contact_service_test.go | 616 +++++++++++++++++++++++
 2 files changed, 795 insertions(+)
 create mode 100644 api/pkg/services/contact_service.go
 create mode 100644 api/pkg/services/contact_service_test.go

diff --git a/api/pkg/services/contact_service.go b/api/pkg/services/contact_service.go
new file mode 100644
index 000000000..005e51f0a
--- /dev/null
+++ b/api/pkg/services/contact_service.go
@@ -0,0 +1,179 @@
+package services
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/cache"
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+)
+
+// contactMapCacheTTL bounds staleness of the cached phone-number -> contact map.
+// A 24h ceiling lets self-healing kick in even if an invalidation write is ever lost.
+const contactMapCacheTTL = 24 * time.Hour
+
+// ContactService owns contact CRUD and the cached phone-number-to-contact map
+// used by higher-level services (e.g. GetThreads) to resolve display names.
+type ContactService struct {
+	service
+	logger     telemetry.Logger
+	tracer     telemetry.Tracer
+	repository repositories.ContactRepository
+	cache      cache.Cache
+}
+
+// NewContactService creates a new ContactService.
+func NewContactService(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	repository repositories.ContactRepository,
+	appCache cache.Cache,
+) (s *ContactService) {
+	return &ContactService{
+		logger:     logger.WithService(fmt.Sprintf("%T", s)),
+		tracer:     tracer,
+		repository: repository,
+		cache:      appCache,
+	}
+}
+
+func (service *ContactService) cacheKey(userID entities.UserID) string {
+	return fmt.Sprintf("contacts.map.%s", userID)
+}
+
+// CreateMany persists one or many contacts in a single batch and invalidates the cached map.
+func (service *ContactService) CreateMany(ctx context.Context, userID entities.UserID, contacts []*entities.Contact) error {
+	ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)
+	defer span.End()
+
+	if err := service.repository.Store(ctx, contacts); err != nil {
+		return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts for user [%s]", len(contacts), userID))
+	}
+
+	service.invalidate(ctx, ctxLogger, userID)
+	return nil
+}
+
+// Get returns a single contact scoped to the user.
+func (service *ContactService) Get(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	contact, err := service.repository.Load(ctx, userID, contactID)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, stacktrace.GetCode(err), "cannot load contact [%s] for user [%s]", contactID, userID))
+	}
+	return contact, nil
+}
+
+// Index lists contacts for a user with the provided search/pagination params.
+func (service *ContactService) Index(ctx context.Context, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	contacts, err := service.repository.Index(ctx, userID, params)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s]", userID))
+	}
+	return contacts, nil
+}
+
+// Update persists changes to a contact and invalidates the cached map.
+func (service *ContactService) Update(ctx context.Context, contact *entities.Contact) error {
+	ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)
+	defer span.End()
+
+	if err := service.repository.Update(ctx, contact); err != nil {
+		return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact [%s] for user [%s]", contact.ID, contact.UserID))
+	}
+
+	service.invalidate(ctx, ctxLogger, contact.UserID)
+	return nil
+}
+
+// Delete removes a contact scoped to the user and invalidates the cached map.
+func (service *ContactService) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {
+	ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)
+	defer span.End()
+
+	if err := service.repository.Delete(ctx, userID, contactID); err != nil {
+		return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))
+	}
+
+	service.invalidate(ctx, ctxLogger, userID)
+	return nil
+}
+
+// GetContactMap returns a phone_number -> *Contact map for the given user, backed by a per-user cache.
+// FetchAll orders by updated_at ASC, so map construction naturally lets the most-recently-updated
+// contact win when two contacts share a phone number.
+func (service *ContactService) GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error) {
+	ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)
+	defer span.End()
+
+	key := service.cacheKey(userID)
+
+	raw, cacheErr := service.cache.Get(ctx, key)
+	switch {
+	case cacheErr != nil:
+		// The Cache interface has no typed miss signal, so a Get error is
+		// treated as "no cached value, rebuild from source". This is expected
+		// on cold starts, so log at Debug — a real fault surfaces via the
+		// subsequent repository/set calls or via cache-level metrics.
+		ctxLogger.Debug(fmt.Sprintf("contact map cache miss for user [%s]: %s", userID, cacheErr.Error()))
+	case raw == "":
+		// Empty string is the invalidation marker written by mutations.
+		ctxLogger.Debug(fmt.Sprintf("contact map cache invalidated for user [%s], rebuilding", userID))
+	default:
+		result := map[string]*entities.Contact{}
+		if err := json.Unmarshal([]byte(raw), &result); err != nil {
+			ctxLogger.Error(stacktrace.Propagatef(err, "cannot unmarshal contact map cache for user [%s], rebuilding", userID))
+		} else {
+			return result, nil
+		}
+	}
+
+	contacts, err := service.repository.FetchAll(ctx, userID)
+	if err != nil {
+		return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts to build map for user [%s]", userID))
+	}
+
+	result := make(map[string]*entities.Contact, len(*contacts))
+	for index := range *contacts {
+		// Take a fresh copy of the slice element so the map holds a stable pointer
+		// that does not alias the underlying slice storage.
+		contact := (*contacts)[index]
+		for _, number := range contact.PhoneNumbers {
+			result[number] = &contact
+		}
+	}
+
+	encoded, err := json.Marshal(result)
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot marshal contact map cache payload for user [%s]", userID))
+		return result, nil
+	}
+	if err := service.cache.Set(ctx, key, string(encoded), contactMapCacheTTL); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot populate contact map cache for user [%s]", userID))
+	}
+
+	return result, nil
+}
+
+// invalidate writes an empty marker under the user's cache key. The Cache
+// interface has no Delete; the marker is treated as a rebuild trigger by
+// GetContactMap. Failures are logged at Error but do not fail the calling
+// mutation: the DB write already succeeded, and the 24h TTL bounds staleness.
+// See docs in contact_service_test.go / task-6-report.md for the rationale.
+func (service *ContactService) invalidate(ctx context.Context, ctxLogger telemetry.Logger, userID entities.UserID) {
+	key := service.cacheKey(userID)
+	if err := service.cache.Set(ctx, key, "", contactMapCacheTTL); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot invalidate contact map cache for user [%s] with key [%s]", userID, key))
+	}
+}
diff --git a/api/pkg/services/contact_service_test.go b/api/pkg/services/contact_service_test.go
new file mode 100644
index 000000000..596a7a5ec
--- /dev/null
+++ b/api/pkg/services/contact_service_test.go
@@ -0,0 +1,616 @@
+package services
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// --- fake cache -------------------------------------------------------------
+
+type fakeCache struct {
+	mu     sync.Mutex
+	store  map[string]string
+	getErr error
+	setErr error
+	sets   []cacheSetCall
+	gets   int
+}
+
+type cacheSetCall struct {
+	key   string
+	value string
+	ttl   time.Duration
+}
+
+func newFakeCache() *fakeCache { return &fakeCache{store: map[string]string{}} }
+
+func (c *fakeCache) Get(_ context.Context, key string) (string, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.gets++
+	if c.getErr != nil {
+		return "", c.getErr
+	}
+	value, ok := c.store[key]
+	if !ok {
+		return "", stacktrace.NewErrorf("no item found in cache with key [%s]", key)
+	}
+	return value, nil
+}
+
+func (c *fakeCache) Set(_ context.Context, key, value string, ttl time.Duration) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.sets = append(c.sets, cacheSetCall{key: key, value: value, ttl: ttl})
+	if c.setErr != nil {
+		return c.setErr
+	}
+	c.store[key] = value
+	return nil
+}
+
+// setsFor returns the recorded Set calls for a given key.
+func (c *fakeCache) setsFor(key string) []cacheSetCall {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	var out []cacheSetCall
+	for _, s := range c.sets {
+		if s.key == key {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// --- fake repository --------------------------------------------------------
+
+type fakeContactRepo struct {
+	mu sync.Mutex
+
+	contacts []*entities.Contact
+
+	storeCalls  [][]*entities.Contact
+	updateCalls []*entities.Contact
+	loadCalls   []loadCall
+	indexCalls  []indexCall
+	deleteCalls []deleteCall
+	fetchAll    int
+
+	storeErr  error
+	updateErr error
+	loadErr   error
+	indexErr  error
+	deleteErr error
+	fetchErr  error
+
+	indexResult []entities.Contact
+}
+
+type loadCall struct {
+	userID entities.UserID
+	id     uuid.UUID
+}
+
+type indexCall struct {
+	userID entities.UserID
+	params repositories.IndexParams
+}
+
+type deleteCall struct {
+	userID entities.UserID
+	id     uuid.UUID
+}
+
+func (r *fakeContactRepo) Store(_ context.Context, contacts []*entities.Contact) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.storeCalls = append(r.storeCalls, contacts)
+	if r.storeErr != nil {
+		return r.storeErr
+	}
+	r.contacts = append(r.contacts, contacts...)
+	return nil
+}
+
+func (r *fakeContactRepo) Update(_ context.Context, contact *entities.Contact) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.updateCalls = append(r.updateCalls, contact)
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	return nil
+}
+
+func (r *fakeContactRepo) Load(_ context.Context, userID entities.UserID, id uuid.UUID) (*entities.Contact, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.loadCalls = append(r.loadCalls, loadCall{userID: userID, id: id})
+	if r.loadErr != nil {
+		return nil, r.loadErr
+	}
+	for _, c := range r.contacts {
+		if c.ID == id && c.UserID == userID {
+			return c, nil
+		}
+	}
+	return nil, stacktrace.NewErrorWithCodef(repositories.ErrCodeNotFound, "contact [%s] not found", id)
+}
+
+func (r *fakeContactRepo) Index(_ context.Context, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.indexCalls = append(r.indexCalls, indexCall{userID: userID, params: params})
+	if r.indexErr != nil {
+		return nil, r.indexErr
+	}
+	out := append([]entities.Contact{}, r.indexResult...)
+	return &out, nil
+}
+
+func (r *fakeContactRepo) FetchAll(_ context.Context, _ entities.UserID) (*[]entities.Contact, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.fetchAll++
+	if r.fetchErr != nil {
+		return nil, r.fetchErr
+	}
+	out := make([]entities.Contact, 0, len(r.contacts))
+	for _, c := range r.contacts {
+		out = append(out, *c)
+	}
+	return &out, nil
+}
+
+func (r *fakeContactRepo) Delete(_ context.Context, userID entities.UserID, id uuid.UUID) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.deleteCalls = append(r.deleteCalls, deleteCall{userID: userID, id: id})
+	return r.deleteErr
+}
+
+func (r *fakeContactRepo) DeleteAllForUser(_ context.Context, _ entities.UserID) error { return nil }
+
+// --- recording logger -------------------------------------------------------
+
+type recordingLogger struct {
+	*noopLogger
+	mu     sync.Mutex
+	errors []error
+	warns  []error
+	infos  []string
+	debugs []string
+}
+
+func newRecordingLogger() *recordingLogger {
+	return &recordingLogger{noopLogger: &noopLogger{}}
+}
+
+func (l *recordingLogger) Error(err error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.errors = append(l.errors, err)
+}
+
+func (l *recordingLogger) Warn(err error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.warns = append(l.warns, err)
+}
+
+func (l *recordingLogger) Info(v string) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.infos = append(l.infos, v)
+}
+
+func (l *recordingLogger) Debug(v string) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.debugs = append(l.debugs, v)
+}
+
+func (l *recordingLogger) WithService(_ string) telemetry.Logger   { return l }
+func (l *recordingLogger) WithString(_, _ string) telemetry.Logger { return l }
+func (l *recordingLogger) WithSpan(_ trace.SpanContext) telemetry.Logger {
+	return l
+}
+
+func (l *recordingLogger) errorCount() int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return len(l.errors)
+}
+
+// --- helpers ---------------------------------------------------------------
+
+func newContactServiceForTest(t *testing.T, repo repositories.ContactRepository, appCache *fakeCache, logger telemetry.Logger) *ContactService {
+	t.Helper()
+	if logger == nil {
+		logger = &noopLogger{}
+	}
+	tracer := telemetry.NewOtelLogger("test", logger)
+	return NewContactService(logger, tracer, repo, appCache)
+}
+
+// --- tests -----------------------------------------------------------------
+
+func TestContactService_GetContactMap_TieBreakMostRecentlyUpdatedWins(t *testing.T) {
+	older := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Old", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now().Add(-time.Hour)}
+	newer := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "New", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now()}
+	repo := &fakeContactRepo{contacts: []*entities.Contact{older, newer}}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	require.NotNil(t, result["+18005550199"])
+	assert.Equal(t, "New", result["+18005550199"].Name)
+	assert.Equal(t, newer.ID, result["+18005550199"].ID)
+}
+
+func TestContactService_GetContactMap_AllPhoneNumbersMapToOneContact(t *testing.T) {
+	contact := &entities.Contact{
+		ID:           uuid.New(),
+		UserID:       "u1",
+		Name:         "Alice",
+		PhoneNumbers: pq.StringArray{"+18005550199", "+18005550100", "+18005550111"},
+	}
+	repo := &fakeContactRepo{contacts: []*entities.Contact{contact}}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	for _, num := range contact.PhoneNumbers {
+		got, ok := result[num]
+		require.True(t, ok, "missing entry for %s", num)
+		assert.Equal(t, contact.ID, got.ID)
+		assert.Equal(t, "Alice", got.Name)
+	}
+}
+
+func TestContactService_GetContactMap_NoCollisionDistinctPointersPerContact(t *testing.T) {
+	a := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now().Add(-2 * time.Hour)}
+	b := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}, UpdatedAt: time.Now().Add(-time.Hour)}
+	c := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Carol", PhoneNumbers: pq.StringArray{"+18005550111"}, UpdatedAt: time.Now()}
+	repo := &fakeContactRepo{contacts: []*entities.Contact{a, b, c}}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	require.Len(t, result, 3)
+	assert.Equal(t, "Alice", result["+18005550199"].Name)
+	assert.Equal(t, "Bob", result["+18005550100"].Name)
+	assert.Equal(t, "Carol", result["+18005550111"].Name)
+
+	// Each entry must point to a stable, independent value.
+	assert.NotSame(t, result["+18005550199"], result["+18005550100"])
+	assert.NotSame(t, result["+18005550100"], result["+18005550111"])
+
+	// Mutating the returned pointer must not corrupt other entries.
+	result["+18005550199"].Name = "Mutated"
+	assert.Equal(t, "Bob", result["+18005550100"].Name)
+	assert.Equal(t, "Carol", result["+18005550111"].Name)
+}
+
+func TestContactService_GetContactMap_CacheHitAvoidsFetchAll(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"},
+	}}}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	_, err = service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, repo.fetchAll, "second call must hit cache")
+}
+
+func TestContactService_GetContactMap_EmptyMarkerTriggersRebuild(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"},
+	}}}
+	appCache := newFakeCache()
+	// Pre-seed the invalidation marker.
+	require.NoError(t, appCache.Set(context.Background(), "contacts.map.u1", "", time.Hour))
+	logger := newRecordingLogger()
+	service := newContactServiceForTest(t, repo, appCache, logger)
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, repo.fetchAll, "empty marker must force rebuild")
+	assert.Equal(t, "Alice", result["+18005550199"].Name)
+	assert.Equal(t, 0, logger.errorCount(), "empty marker rebuild must not log an error")
+}
+
+func TestContactService_GetContactMap_CorruptCacheRebuildsAndLogs(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"},
+	}}}
+	appCache := newFakeCache()
+	require.NoError(t, appCache.Set(context.Background(), "contacts.map.u1", "not-json{", time.Hour))
+	logger := newRecordingLogger()
+	service := newContactServiceForTest(t, repo, appCache, logger)
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, repo.fetchAll, "corrupt cache must force rebuild")
+	assert.Equal(t, "Alice", result["+18005550199"].Name)
+	assert.GreaterOrEqual(t, logger.errorCount(), 1, "corrupt cache must log an error")
+}
+
+func TestContactService_GetContactMap_CachePopulationErrorReturnsMapAndLogs(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"},
+	}}}
+	appCache := newFakeCache()
+	appCache.setErr = errors.New("boom")
+	logger := newRecordingLogger()
+	service := newContactServiceForTest(t, repo, appCache, logger)
+
+	result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err, "population failure must not fail the caller")
+	require.NotNil(t, result["+18005550199"])
+	assert.Equal(t, "Alice", result["+18005550199"].Name)
+	assert.GreaterOrEqual(t, logger.errorCount(), 1, "population failure must be logged")
+}
+
+func TestContactService_GetContactMap_CachedRoundTripPreservesData(t *testing.T) {
+	// After the first call populates the cache, verify the cached payload is well-formed JSON
+	// mapping phone numbers to contact objects and that a second call returns equivalent data.
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{
+		ID:           uuid.New(),
+		UserID:       "u1",
+		Name:         "Alice",
+		PhoneNumbers: pq.StringArray{"+18005550199", "+18005550100"},
+	}}}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	first, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+
+	raw, err := appCache.Get(context.Background(), "contacts.map.u1")
+	require.NoError(t, err)
+	require.NotEmpty(t, raw)
+
+	decoded := map[string]*entities.Contact{}
+	require.NoError(t, json.Unmarshal([]byte(raw), &decoded))
+	assert.Equal(t, first["+18005550199"].ID, decoded["+18005550199"].ID)
+
+	second, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	assert.Equal(t, first["+18005550199"].ID, second["+18005550199"].ID)
+	assert.Equal(t, first["+18005550100"].ID, second["+18005550100"].ID)
+}
+
+// --- mutation invalidation tests ------------------------------------------
+
+func TestContactService_CreateMany_InvalidatesCacheExactlyOnce(t *testing.T) {
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"},
+	}}}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	// Warm the cache.
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	require.Equal(t, 1, repo.fetchAll)
+
+	setsBefore := len(appCache.setsFor("contacts.map.u1"))
+
+	added := []*entities.Contact{
+		{ID: uuid.New(), UserID: "u1", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},
+		{ID: uuid.New(), UserID: "u1", Name: "Carol", PhoneNumbers: pq.StringArray{"+18005550111"}},
+	}
+	require.NoError(t, service.CreateMany(context.Background(), entities.UserID("u1"), added))
+
+	assert.Len(t, repo.storeCalls, 1, "batch must be persisted in a single Store call")
+	assert.Equal(t, added, repo.storeCalls[0])
+
+	afterInvalidation := appCache.setsFor("contacts.map.u1")
+	require.Len(t, afterInvalidation, setsBefore+1, "CreateMany must invalidate the cache exactly once")
+	assert.Equal(t, "", afterInvalidation[len(afterInvalidation)-1].value, "invalidation marker must be empty")
+
+	// Next GetContactMap rebuilds.
+	_, err = service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	assert.Equal(t, 2, repo.fetchAll)
+}
+
+func TestContactService_Update_InvalidatesCacheExactlyOnce(t *testing.T) {
+	c := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}
+	repo := &fakeContactRepo{contacts: []*entities.Contact{c}}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	setsBefore := len(appCache.setsFor("contacts.map.u1"))
+
+	updated := *c
+	updated.Name = "Alicia"
+	require.NoError(t, service.Update(context.Background(), &updated))
+
+	require.Len(t, repo.updateCalls, 1)
+	assert.Equal(t, "Alicia", repo.updateCalls[0].Name)
+	assert.Equal(t, entities.UserID("u1"), repo.updateCalls[0].UserID)
+
+	afterInvalidation := appCache.setsFor("contacts.map.u1")
+	require.Len(t, afterInvalidation, setsBefore+1)
+	assert.Equal(t, "", afterInvalidation[len(afterInvalidation)-1].value)
+}
+
+func TestContactService_Delete_InvalidatesCacheExactlyOnce(t *testing.T) {
+	id := uuid.New()
+	repo := &fakeContactRepo{contacts: []*entities.Contact{{ID: id, UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.NoError(t, err)
+	setsBefore := len(appCache.setsFor("contacts.map.u1"))
+
+	require.NoError(t, service.Delete(context.Background(), entities.UserID("u1"), id))
+
+	require.Len(t, repo.deleteCalls, 1)
+	assert.Equal(t, deleteCall{userID: "u1", id: id}, repo.deleteCalls[0])
+
+	afterInvalidation := appCache.setsFor("contacts.map.u1")
+	require.Len(t, afterInvalidation, setsBefore+1)
+	assert.Equal(t, "", afterInvalidation[len(afterInvalidation)-1].value)
+}
+
+func TestContactService_InvalidationFailure_LogsErrorButReturnsNil(t *testing.T) {
+	// Persistence succeeded but cache invalidation failed. The mutation itself
+	// must not return an error (see report: chosen contract), but MUST log the
+	// invalidation failure explicitly at Error level so operators are alerted.
+	repo := &fakeContactRepo{}
+	appCache := newFakeCache()
+	appCache.setErr = errors.New("cache down")
+	logger := newRecordingLogger()
+	service := newContactServiceForTest(t, repo, appCache, logger)
+
+	err := service.CreateMany(context.Background(), entities.UserID("u1"), []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"},
+	}})
+	require.NoError(t, err, "mutation must not surface invalidation failure to caller")
+
+	// Repository actually got the write.
+	require.Len(t, repo.storeCalls, 1)
+	// The invalidation attempt was logged as an error.
+	assert.GreaterOrEqual(t, logger.errorCount(), 1, "invalidation failure must be logged as error")
+}
+
+// --- CRUD delegation and user scope tests ---------------------------------
+
+func TestContactService_CreateMany_PersistsBatchInSingleCall(t *testing.T) {
+	repo := &fakeContactRepo{}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	batch := []*entities.Contact{
+		{ID: uuid.New(), UserID: "u1", Name: "A", PhoneNumbers: pq.StringArray{"+18005550100"}},
+		{ID: uuid.New(), UserID: "u1", Name: "B", PhoneNumbers: pq.StringArray{"+18005550111"}},
+	}
+	require.NoError(t, service.CreateMany(context.Background(), entities.UserID("u1"), batch))
+
+	require.Len(t, repo.storeCalls, 1)
+	assert.Equal(t, batch, repo.storeCalls[0])
+}
+
+func TestContactService_CreateMany_RepositoryErrorIsWrapped(t *testing.T) {
+	repo := &fakeContactRepo{storeErr: errors.New("db down")}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	err := service.CreateMany(context.Background(), entities.UserID("u1"), []*entities.Contact{{
+		ID: uuid.New(), UserID: "u1", Name: "A", PhoneNumbers: pq.StringArray{"+18005550100"},
+	}})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "db down")
+}
+
+func TestContactService_Get_DelegatesWithUserScope(t *testing.T) {
+	id := uuid.New()
+	other := uuid.New()
+	repo := &fakeContactRepo{contacts: []*entities.Contact{
+		{ID: id, UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},
+		{ID: other, UserID: "u2", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},
+	}}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	got, err := service.Get(context.Background(), entities.UserID("u1"), id)
+	require.NoError(t, err)
+	assert.Equal(t, "Alice", got.Name)
+
+	// Wrong user scope must not resolve the contact.
+	_, err = service.Get(context.Background(), entities.UserID("u1"), other)
+	require.Error(t, err)
+	assert.Equal(t, repositories.ErrCodeNotFound, stacktrace.GetCode(err))
+}
+
+func TestContactService_Index_DelegatesParams(t *testing.T) {
+	want := []entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}
+	repo := &fakeContactRepo{indexResult: want}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	params := repositories.IndexParams{Skip: 5, Limit: 10, SortBy: "name", Query: "Ali"}
+	got, err := service.Index(context.Background(), entities.UserID("u1"), params)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+	assert.Equal(t, want, *got)
+
+	require.Len(t, repo.indexCalls, 1)
+	assert.Equal(t, entities.UserID("u1"), repo.indexCalls[0].userID)
+	assert.Equal(t, params, repo.indexCalls[0].params)
+}
+
+func TestContactService_Index_RepositoryErrorIsWrapped(t *testing.T) {
+	repo := &fakeContactRepo{indexErr: errors.New("index boom")}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	_, err := service.Index(context.Background(), entities.UserID("u1"), repositories.IndexParams{})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "index boom")
+}
+
+func TestContactService_Update_RepositoryErrorIsWrappedAndSkipsInvalidation(t *testing.T) {
+	repo := &fakeContactRepo{updateErr: errors.New("update boom")}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	err := service.Update(context.Background(), &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "A", PhoneNumbers: pq.StringArray{"+18005550100"}})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "update boom")
+	assert.Len(t, appCache.setsFor("contacts.map.u1"), 0, "invalidation must not run when the write fails")
+}
+
+func TestContactService_Delete_RepositoryErrorIsWrappedAndSkipsInvalidation(t *testing.T) {
+	repo := &fakeContactRepo{deleteErr: errors.New("delete boom")}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	err := service.Delete(context.Background(), entities.UserID("u1"), uuid.New())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "delete boom")
+	assert.Len(t, appCache.setsFor("contacts.map.u1"), 0)
+}
+
+func TestContactService_GetContactMap_FetchAllErrorIsWrapped(t *testing.T) {
+	repo := &fakeContactRepo{fetchErr: errors.New("fetch boom")}
+	appCache := newFakeCache()
+	service := newContactServiceForTest(t, repo, appCache, nil)
+
+	_, err := service.GetContactMap(context.Background(), entities.UserID("u1"))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "fetch boom")
+}

From 5ec3d8db98fbf2334d9d93c429af1349965b1da5 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 22:42:29 +0300
Subject: [PATCH 11/24] feat(api): opt in contact resolution

Add contacts query parsing and optional ContactDetails enrichment through a contact map provider.

DI passes nil until Task 8 wires ContactService.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/docs/docs.go                              |  74 +++++++++
 api/docs/swagger.json                         |  74 +++++++++
 api/docs/swagger.yaml                         |  52 ++++++
 api/pkg/di/container.go                       |   1 +
 api/pkg/handlers/message_thread_handler.go    |   1 +
 .../message_thread_handler_contacts_test.go   |  75 +++++++++
 .../handlers/message_thread_handler_test.go   |   2 +-
 .../listeners/message_thread_listener_test.go |   2 +-
 .../requests/message_thread_index_request.go  |  17 +-
 .../message_thread_index_request_test.go      |  40 +++++
 api/pkg/services/message_thread_service.go    |  27 ++-
 .../message_thread_service_contacts_test.go   | 154 ++++++++++++++++++
 .../services/message_thread_service_test.go   |   2 +-
 13 files changed, 512 insertions(+), 9 deletions(-)
 create mode 100644 api/pkg/handlers/message_thread_handler_contacts_test.go
 create mode 100644 api/pkg/requests/message_thread_index_request_test.go
 create mode 100644 api/pkg/services/message_thread_service_contacts_test.go

diff --git a/api/docs/docs.go b/api/docs/docs.go
index 8cd408cb1..41653fafc 100644
--- a/api/docs/docs.go
+++ b/api/docs/docs.go
@@ -794,6 +794,12 @@ const docTemplate = `{
                         "description": "number of messages to return",
                         "name": "limit",
                         "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "include matching contact details",
+                        "name": "contacts",
+                        "in": "query"
                     }
                 ],
                 "responses": {
@@ -3401,6 +3407,66 @@ const docTemplate = `{
                 }
             }
         },
+        "entities.Contact": {
+            "type": "object",
+            "required": [
+                "created_at",
+                "emails",
+                "id",
+                "name",
+                "phone_numbers",
+                "properties",
+                "updated_at",
+                "user_id"
+            ],
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2022-06-05T14:26:02.302718+03:00"
+                },
+                "emails": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "alice@example.com"
+                    ]
+                },
+                "id": {
+                    "type": "string",
+                    "example": "32343a19-da5e-4b1b-a767-3298a73703cb"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Alice Smith"
+                },
+                "phone_numbers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "+18005550199",
+                        "+18005550100"
+                    ]
+                },
+                "properties": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2022-06-05T14:26:02.302718+03:00"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "WB7DRDWrJZRGbYrv2CKGkqbzvqdC"
+                }
+            }
+        },
         "entities.Discord": {
             "type": "object",
             "required": [
@@ -3715,6 +3781,14 @@ const docTemplate = `{
                     "type": "string",
                     "example": "+18005550100"
                 },
+                "contact_details": {
+                    "description": "ContactDetails is resolved at read time and never persisted.",
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/entities.Contact"
+                        }
+                    ]
+                },
                 "created_at": {
                     "type": "string",
                     "example": "2022-06-05T14:26:09.527976+03:00"
diff --git a/api/docs/swagger.json b/api/docs/swagger.json
index ac9c12c98..3f70ef926 100644
--- a/api/docs/swagger.json
+++ b/api/docs/swagger.json
@@ -791,6 +791,12 @@
                         "description": "number of messages to return",
                         "name": "limit",
                         "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "include matching contact details",
+                        "name": "contacts",
+                        "in": "query"
                     }
                 ],
                 "responses": {
@@ -3398,6 +3404,66 @@
                 }
             }
         },
+        "entities.Contact": {
+            "type": "object",
+            "required": [
+                "created_at",
+                "emails",
+                "id",
+                "name",
+                "phone_numbers",
+                "properties",
+                "updated_at",
+                "user_id"
+            ],
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2022-06-05T14:26:02.302718+03:00"
+                },
+                "emails": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "alice@example.com"
+                    ]
+                },
+                "id": {
+                    "type": "string",
+                    "example": "32343a19-da5e-4b1b-a767-3298a73703cb"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Alice Smith"
+                },
+                "phone_numbers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "+18005550199",
+                        "+18005550100"
+                    ]
+                },
+                "properties": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2022-06-05T14:26:02.302718+03:00"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "WB7DRDWrJZRGbYrv2CKGkqbzvqdC"
+                }
+            }
+        },
         "entities.Discord": {
             "type": "object",
             "required": [
@@ -3712,6 +3778,14 @@
                     "type": "string",
                     "example": "+18005550100"
                 },
+                "contact_details": {
+                    "description": "ContactDetails is resolved at read time and never persisted.",
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/entities.Contact"
+                        }
+                    ]
+                },
                 "created_at": {
                     "type": "string",
                     "example": "2022-06-05T14:26:09.527976+03:00"
diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yaml
index ddc6ae700..a83c943fd 100644
--- a/api/docs/swagger.yaml
+++ b/api/docs/swagger.yaml
@@ -80,6 +80,50 @@ definitions:
     - sent_count
     - total
     type: object
+  entities.Contact:
+    properties:
+      created_at:
+        example: "2022-06-05T14:26:02.302718+03:00"
+        type: string
+      emails:
+        example:
+        - alice@example.com
+        items:
+          type: string
+        type: array
+      id:
+        example: 32343a19-da5e-4b1b-a767-3298a73703cb
+        type: string
+      name:
+        example: Alice Smith
+        type: string
+      phone_numbers:
+        example:
+        - "+18005550199"
+        - "+18005550100"
+        items:
+          type: string
+        type: array
+      properties:
+        additionalProperties:
+          type: string
+        type: object
+      updated_at:
+        example: "2022-06-05T14:26:02.302718+03:00"
+        type: string
+      user_id:
+        example: WB7DRDWrJZRGbYrv2CKGkqbzvqdC
+        type: string
+    required:
+    - created_at
+    - emails
+    - id
+    - name
+    - phone_numbers
+    - properties
+    - updated_at
+    - user_id
+    type: object
   entities.Discord:
     properties:
       created_at:
@@ -310,6 +354,10 @@ definitions:
       contact:
         example: "+18005550100"
         type: string
+      contact_details:
+        allOf:
+        - $ref: '#/definitions/entities.Contact'
+        description: ContactDetails is resolved at read time and never persisted.
       created_at:
         example: "2022-06-05T14:26:09.527976+03:00"
         type: string
@@ -2106,6 +2154,10 @@ paths:
         minimum: 1
         name: limit
         type: integer
+      - description: include matching contact details
+        in: query
+        name: contacts
+        type: boolean
       produces:
       - application/json
       responses:
diff --git a/api/pkg/di/container.go b/api/pkg/di/container.go
index 043c897ab..2719fb9d3 100644
--- a/api/pkg/di/container.go
+++ b/api/pkg/di/container.go
@@ -1114,6 +1114,7 @@ func (container *Container) MessageThreadService() (service *services.MessageThr
 		container.MessageThreadRepository(),
 		container.PhoneRepository(),
 		container.EventDispatcher(),
+		nil,
 	)
 }
 
diff --git a/api/pkg/handlers/message_thread_handler.go b/api/pkg/handlers/message_thread_handler.go
index a931302dc..72e0b543d 100644
--- a/api/pkg/handlers/message_thread_handler.go
+++ b/api/pkg/handlers/message_thread_handler.go
@@ -57,6 +57,7 @@ func (h *MessageThreadHandler) RegisterRoutes(router fiber.Router, middlewares .
 // @Param        skip	query  int  	false	"number of messages to skip"				minimum(0)
 // @Param        query	query  string  	false 	"filter message threads containing query"
 // @Param        limit	query  int  	false	"number of messages to return"				minimum(1)	maximum(20)
+// @Param        contacts	query  bool  	false	"include matching contact details"
 // @Success      200 	{object}	responses.MessageThreadsResponse
 // @Failure      400	{object}	responses.BadRequest
 // @Failure 	 401    {object}	responses.Unauthorized
diff --git a/api/pkg/handlers/message_thread_handler_contacts_test.go b/api/pkg/handlers/message_thread_handler_contacts_test.go
new file mode 100644
index 000000000..22d6a98bb
--- /dev/null
+++ b/api/pkg/handlers/message_thread_handler_contacts_test.go
@@ -0,0 +1,75 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/middlewares"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/services"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/httpsms/pkg/validators"
+	"github.com/gofiber/fiber/v3"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type messageThreadHandlerIndexRepositoryStub struct {
+	repositories.MessageThreadRepository
+	threads []entities.MessageThread
+}
+
+func (stub *messageThreadHandlerIndexRepositoryStub) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {
+	threads := make([]entities.MessageThread, len(stub.threads))
+	copy(threads, stub.threads)
+	return &threads, nil
+}
+
+type messageThreadHandlerContactProviderStub struct {
+	contacts map[string]*entities.Contact
+	calls    int
+}
+
+func (stub *messageThreadHandlerContactProviderStub) GetContactMap(context.Context, entities.UserID) (map[string]*entities.Contact, error) {
+	stub.calls++
+	return stub.contacts, nil
+}
+
+func TestMessageThreadHandlerIndex_ParsesContactsQuery(t *testing.T) {
+	contact := &entities.Contact{ID: uuid.New(), Name: "Alice", PhoneNumbers: []string{"+18005550100"}}
+	repository := &messageThreadHandlerIndexRepositoryStub{threads: []entities.MessageThread{{Contact: "+18005550100"}}}
+	provider := &messageThreadHandlerContactProviderStub{contacts: map[string]*entities.Contact{"+18005550100": contact}}
+	logger := &messageThreadHandlerNoopLogger{}
+	tracer := telemetry.NewOtelLogger("test", logger)
+	service := services.NewMessageThreadService(logger, tracer, repository, nil, nil, provider)
+	handler := NewMessageThreadHandler(logger, tracer, validators.NewMessageThreadHandlerValidator(logger, tracer), service)
+
+	app := fiber.New()
+	app.Use(func(c fiber.Ctx) error {
+		c.Locals(middlewares.ContextKeyAuthUserID, entities.AuthContext{ID: entities.UserID("user-id"), Email: "user@example.com"})
+		return c.Next()
+	})
+	handler.RegisterRoutes(app)
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/message-threads?owner=%2B18005550199&contacts=true", nil)
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+
+	require.NoError(t, err)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Equal(t, 1, provider.calls)
+
+	var payload struct {
+		Data []entities.MessageThread `json:"data"`
+	}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&payload))
+	require.Len(t, payload.Data, 1)
+	require.NotNil(t, payload.Data[0].ContactDetails)
+	assert.Equal(t, contact.ID, payload.Data[0].ContactDetails.ID)
+	assert.Equal(t, "Alice", payload.Data[0].ContactDetails.Name)
+}
diff --git a/api/pkg/handlers/message_thread_handler_test.go b/api/pkg/handlers/message_thread_handler_test.go
index fefb81895..56dfa0c79 100644
--- a/api/pkg/handlers/message_thread_handler_test.go
+++ b/api/pkg/handlers/message_thread_handler_test.go
@@ -64,7 +64,7 @@ func (stub *messageThreadHandlerRepositoryStub) DeleteAllForUser(context.Context
 func TestMessageThreadHandlerUpdate_ReturnsNotFoundWhenThreadIsMissing(t *testing.T) {
 	logger := &messageThreadHandlerNoopLogger{}
 	tracer := telemetry.NewOtelLogger("test", logger)
-	service := services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil)
+	service := services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil, nil)
 	handler := NewMessageThreadHandler(logger, tracer, validators.NewMessageThreadHandlerValidator(logger, tracer), service)
 
 	app := fiber.New()
diff --git a/api/pkg/listeners/message_thread_listener_test.go b/api/pkg/listeners/message_thread_listener_test.go
index 39a444cce..f0410dfaa 100644
--- a/api/pkg/listeners/message_thread_listener_test.go
+++ b/api/pkg/listeners/message_thread_listener_test.go
@@ -66,7 +66,7 @@ func newMessageThreadListenerForTest() (*listenerMessageThreadRepository, map[st
 	repository := &listenerMessageThreadRepository{}
 	logger := &noopListenerLogger{}
 	tracer := telemetry.NewOtelLogger("test", logger)
-	service := services.NewMessageThreadService(logger, tracer, repository, nil, nil)
+	service := services.NewMessageThreadService(logger, tracer, repository, nil, nil, nil)
 	_, routes := NewMessageThreadListener(logger, tracer, service)
 	return repository, routes
 }
diff --git a/api/pkg/requests/message_thread_index_request.go b/api/pkg/requests/message_thread_index_request.go
index 53157df55..053f90003 100644
--- a/api/pkg/requests/message_thread_index_request.go
+++ b/api/pkg/requests/message_thread_index_request.go
@@ -18,6 +18,7 @@ type MessageThreadIndex struct {
 	Query      string `json:"query" query:"query"`
 	Limit      string `json:"limit" query:"limit"`
 	Owner      string `json:"owner" query:"owner"`
+	Contacts   string `json:"contacts" query:"contacts" example:"false"`
 }
 
 // Sanitize sets defaults to MessageOutstanding
@@ -30,7 +31,16 @@ func (input *MessageThreadIndex) Sanitize() MessageThreadIndex {
 		input.IsArchived = "false"
 	}
 
+	if strings.TrimSpace(input.Contacts) == "" {
+		input.Contacts = "false"
+	}
+
 	input.IsArchived = input.sanitizeBool(input.IsArchived)
+	input.Contacts = input.sanitizeBool(input.Contacts)
+	if input.Contacts != "true" && input.Contacts != "false" {
+		input.Contacts = "false"
+	}
+
 	input.Query = strings.TrimSpace(input.Query)
 	input.Owner = input.sanitizeAddress(input.Owner)
 
@@ -50,8 +60,9 @@ func (input *MessageThreadIndex) ToGetParams(userID entities.UserID) services.Me
 			Query: input.Query,
 			Limit: input.getInt(input.Limit),
 		},
-		UserID:     userID,
-		IsArchived: input.getBool(input.IsArchived),
-		Owner:      input.Owner,
+		UserID:       userID,
+		IsArchived:   input.getBool(input.IsArchived),
+		WithContacts: input.getBool(input.Contacts),
+		Owner:        input.Owner,
 	}
 }
diff --git a/api/pkg/requests/message_thread_index_request_test.go b/api/pkg/requests/message_thread_index_request_test.go
new file mode 100644
index 000000000..fc7f7b0ed
--- /dev/null
+++ b/api/pkg/requests/message_thread_index_request_test.go
@@ -0,0 +1,40 @@
+package requests
+
+import (
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMessageThreadIndex_ToGetParams_WithContactsTrue(t *testing.T) {
+	input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: " true "}).Sanitize()
+	params := input.ToGetParams(entities.UserID("user-id"))
+
+	assert.Equal(t, "true", input.Contacts)
+	assert.True(t, params.WithContacts)
+}
+
+func TestMessageThreadIndex_ToGetParams_WithContactsFalse(t *testing.T) {
+	input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: "0"}).Sanitize()
+	params := input.ToGetParams(entities.UserID("user-id"))
+
+	assert.Equal(t, "false", input.Contacts)
+	assert.False(t, params.WithContacts)
+}
+
+func TestMessageThreadIndex_ToGetParams_WithContactsDefaultsFalse(t *testing.T) {
+	input := (&MessageThreadIndex{Owner: "+18005550199"}).Sanitize()
+	params := input.ToGetParams(entities.UserID("user-id"))
+
+	assert.Equal(t, "false", input.Contacts)
+	assert.False(t, params.WithContacts)
+}
+
+func TestMessageThreadIndex_ToGetParams_WithContactsInvalidNormalizesFalse(t *testing.T) {
+	input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: "definitely"}).Sanitize()
+	params := input.ToGetParams(entities.UserID("user-id"))
+
+	assert.Equal(t, "false", input.Contacts)
+	assert.False(t, params.WithContacts)
+}
diff --git a/api/pkg/services/message_thread_service.go b/api/pkg/services/message_thread_service.go
index 532a223e2..a0eec53c4 100644
--- a/api/pkg/services/message_thread_service.go
+++ b/api/pkg/services/message_thread_service.go
@@ -15,6 +15,10 @@ import (
 	"github.com/google/uuid"
 )
 
+type contactMapProvider interface {
+	GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error)
+}
+
 // MessageThreadService is handles message requests
 type MessageThreadService struct {
 	service
@@ -23,6 +27,7 @@ type MessageThreadService struct {
 	repository      repositories.MessageThreadRepository
 	phoneRepository repositories.PhoneRepository
 	eventDispatcher *EventDispatcher
+	contactService  contactMapProvider
 }
 
 // NewMessageThreadService creates a new MessageThreadService
@@ -32,6 +37,7 @@ func NewMessageThreadService(
 	repository repositories.MessageThreadRepository,
 	phoneRepository repositories.PhoneRepository,
 	eventDispatcher *EventDispatcher,
+	contactService contactMapProvider,
 ) (s *MessageThreadService) {
 	return &MessageThreadService{
 		logger:          logger.WithService(fmt.Sprintf("%T", s)),
@@ -39,6 +45,7 @@ func NewMessageThreadService(
 		eventDispatcher: eventDispatcher,
 		repository:      repository,
 		phoneRepository: phoneRepository,
+		contactService:  contactService,
 	}
 }
 
@@ -265,9 +272,10 @@ func (service *MessageThreadService) getColor() string {
 // MessageThreadGetParams parameters fetching threads
 type MessageThreadGetParams struct {
 	repositories.IndexParams
-	IsArchived bool
-	UserID     entities.UserID
-	Owner      string
+	IsArchived   bool
+	WithContacts bool
+	UserID       entities.UserID
+	Owner        string
 }
 
 // GetThreads fetches threads for an owner
@@ -282,6 +290,19 @@ func (service *MessageThreadService) GetThreads(ctx context.Context, params Mess
 		return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "could not fetch messages threads for params [%+#v]", params))
 	}
 
+	if params.WithContacts && service.contactService != nil && len(*threads) > 0 {
+		contactMap, mapErr := service.contactService.GetContactMap(ctx, params.UserID)
+		if mapErr != nil {
+			ctxLogger.Error(service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(mapErr, "cannot build contact map for user [%s]", params.UserID)))
+		} else {
+			for index := range *threads {
+				if contact, ok := contactMap[(*threads)[index].Contact]; ok {
+					(*threads)[index].ContactDetails = contact
+				}
+			}
+		}
+	}
+
 	ctxLogger.Info(fmt.Sprintf("fetched [%d] threads with params [%+#v]", len(*threads), params))
 	return threads, nil
 }
diff --git a/api/pkg/services/message_thread_service_contacts_test.go b/api/pkg/services/message_thread_service_contacts_test.go
new file mode 100644
index 000000000..bd592811d
--- /dev/null
+++ b/api/pkg/services/message_thread_service_contacts_test.go
@@ -0,0 +1,154 @@
+package services
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel/trace"
+)
+
+type messageThreadContactRepositoryStub struct {
+	repositories.MessageThreadRepository
+	threads []entities.MessageThread
+	err     error
+	calls   int
+}
+
+func (stub *messageThreadContactRepositoryStub) Index(_ context.Context, _ entities.UserID, _ string, _ bool, _ repositories.IndexParams) (*[]entities.MessageThread, error) {
+	stub.calls++
+	if stub.err != nil {
+		return nil, stub.err
+	}
+	threads := make([]entities.MessageThread, len(stub.threads))
+	copy(threads, stub.threads)
+	return &threads, nil
+}
+
+type messageThreadContactProviderStub struct {
+	contacts map[string]*entities.Contact
+	err      error
+	calls    int
+	userID   entities.UserID
+}
+
+func (stub *messageThreadContactProviderStub) GetContactMap(_ context.Context, userID entities.UserID) (map[string]*entities.Contact, error) {
+	stub.calls++
+	stub.userID = userID
+	return stub.contacts, stub.err
+}
+
+type messageThreadContactLogger struct {
+	errors []error
+}
+
+var _ telemetry.Logger = (*messageThreadContactLogger)(nil)
+
+func (logger *messageThreadContactLogger) Error(err error) {
+	logger.errors = append(logger.errors, err)
+}
+func (logger *messageThreadContactLogger) WithService(string) telemetry.Logger { return logger }
+func (logger *messageThreadContactLogger) WithString(string, string) telemetry.Logger { return logger }
+
+func (logger *messageThreadContactLogger) WithSpan(trace.SpanContext) telemetry.Logger { return logger }
+func (logger *messageThreadContactLogger) Trace(string)                                {}
+func (logger *messageThreadContactLogger) Info(string)                                 {}
+func (logger *messageThreadContactLogger) Warn(error)                                  {}
+func (logger *messageThreadContactLogger) Debug(string)                                {}
+func (logger *messageThreadContactLogger) Fatal(error)                                 {}
+func (logger *messageThreadContactLogger) Printf(string, ...interface{})               {}
+
+func newMessageThreadContactServiceForTest(repository repositories.MessageThreadRepository, provider contactMapProvider, logger telemetry.Logger) *MessageThreadService {
+	if logger == nil {
+		logger = &noopLogger{}
+	}
+	tracer := telemetry.NewOtelLogger("test", logger)
+	return NewMessageThreadService(logger, tracer, repository, nil, nil, provider)
+}
+
+func TestGetThreads_SkipsContactLookupWhenFlagOff(t *testing.T) {
+	repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{{Contact: "+18005550199"}}}
+	provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{
+		"+18005550199": {Name: "Alice"},
+	}}
+	service := newMessageThreadContactServiceForTest(repository, provider, nil)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: false})
+
+	require.NoError(t, err)
+	require.Len(t, *threads, 1)
+	assert.Nil(t, (*threads)[0].ContactDetails)
+	assert.Equal(t, 0, provider.calls)
+}
+
+func TestGetThreads_AttachesContactDetailsWhenFlagOn(t *testing.T) {
+	alice := &entities.Contact{ID: uuid.New(), Name: "Alice", PhoneNumbers: []string{"+18005550199"}}
+	repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{
+		{Contact: "+18005550199"},
+		{Contact: "+18005550100"},
+	}}
+	provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{
+		"+18005550199": alice,
+	}}
+	service := newMessageThreadContactServiceForTest(repository, provider, nil)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})
+
+	require.NoError(t, err)
+	require.Len(t, *threads, 2)
+	assert.Equal(t, 1, provider.calls)
+	assert.Equal(t, entities.UserID("user-id"), provider.userID)
+	require.NotNil(t, (*threads)[0].ContactDetails)
+	assert.Same(t, alice, (*threads)[0].ContactDetails)
+	assert.Equal(t, "Alice", (*threads)[0].ContactDetails.Name)
+	assert.Nil(t, (*threads)[1].ContactDetails)
+}
+
+func TestGetThreads_SkipsContactLookupWhenNoThreads(t *testing.T) {
+	repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{}}
+	provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{}}
+	service := newMessageThreadContactServiceForTest(repository, provider, nil)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})
+
+	require.NoError(t, err)
+	require.Empty(t, *threads)
+	assert.Equal(t, 0, provider.calls)
+}
+
+func TestGetThreads_LogsContactMapErrorAndReturnsThreads(t *testing.T) {
+	repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{{Contact: "+18005550199"}}}
+	provider := &messageThreadContactProviderStub{err: errors.New("contacts unavailable")}
+	logger := &messageThreadContactLogger{}
+	service := newMessageThreadContactServiceForTest(repository, provider, logger)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})
+
+	require.NoError(t, err)
+	require.Len(t, *threads, 1)
+	assert.Nil(t, (*threads)[0].ContactDetails)
+	assert.Equal(t, 1, provider.calls)
+	require.Len(t, logger.errors, 1)
+	assert.ErrorContains(t, logger.errors[0], "cannot build contact map")
+}
+
+func TestGetThreads_DoesNotLookupContactsWhenRepositoryFails(t *testing.T) {
+	repository := &messageThreadContactRepositoryStub{err: stacktrace.NewError("repository failed")}
+	provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{
+		"+18005550199": {Name: "Alice"},
+	}}
+	service := newMessageThreadContactServiceForTest(repository, provider, nil)
+
+	threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})
+
+	require.Error(t, err)
+	assert.Nil(t, threads)
+	assert.Equal(t, 0, provider.calls)
+}
diff --git a/api/pkg/services/message_thread_service_test.go b/api/pkg/services/message_thread_service_test.go
index 8cc8bdcbe..44a3bcfdd 100644
--- a/api/pkg/services/message_thread_service_test.go
+++ b/api/pkg/services/message_thread_service_test.go
@@ -72,7 +72,7 @@ func (stub *messageThreadRepositoryStub) DeleteAllForUser(context.Context, entit
 func newMessageThreadServiceForTest(repository repositories.MessageThreadRepository) *MessageThreadService {
 	logger := &noopLogger{}
 	tracer := telemetry.NewOtelLogger("test", logger)
-	return NewMessageThreadService(logger, tracer, repository, nil, nil)
+	return NewMessageThreadService(logger, tracer, repository, nil, nil, nil)
 }
 
 func TestUpdateThreadPassesUnreadWatermarkForInboundActivity(t *testing.T) {

From 77c20b85fd965360678f7e3f560f5fcf34442df0 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 22:55:19 +0300
Subject: [PATCH 12/24] feat(api): add ContactHandler and wire contacts into DI
 container

- Add ContactHandler with authenticated /v1/contacts routes:
  GET/POST /v1/contacts, POST /v1/contacts/upload,
  PUT/DELETE /v1/contacts/:contactID.
- Load user-scoped contact before Update/Delete so a missing or
  cross-user contact returns 404 (avoids the repo's zero-row Delete
  returning 204 while advertising 404).
- Support one-and-many JSON create via ContactStoreRequest and
  reuse ContactService.CreateMany so cache invalidation stays
  single-shot for Store and CSV upload alike.
- Add DI getters ContactRepository, ContactService,
  ContactHandlerValidator, ContactHandler and RegisterContactRoutes;
  register the routes alongside RegisterMessageThreadRoutes.
- Finalise Task 7 by injecting container.ContactService() into
  MessageThreadService, replacing the temporary nil dependency.
- Cover all five routes with real Fiber requests plus a shared
  ContactRepository fake that verifies service/repository effects,
  and pin the DI wiring with a compile-time test that constructs
  MessageThreadService with the ContactService.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/di/container.go                  |  51 ++-
 api/pkg/handlers/contact_handler.go      | 274 ++++++++++++
 api/pkg/handlers/contact_handler_test.go | 509 +++++++++++++++++++++++
 3 files changed, 833 insertions(+), 1 deletion(-)
 create mode 100644 api/pkg/handlers/contact_handler.go
 create mode 100644 api/pkg/handlers/contact_handler_test.go

diff --git a/api/pkg/di/container.go b/api/pkg/di/container.go
index 2719fb9d3..faff01382 100644
--- a/api/pkg/di/container.go
+++ b/api/pkg/di/container.go
@@ -123,6 +123,8 @@ func NewContainer(projectID string, version string) (container *Container) {
 	container.RegisterMessageThreadRoutes()
 	container.RegisterMessageThreadListeners()
 
+	container.RegisterContactRoutes()
+
 	container.RegisterHeartbeatRoutes()
 	container.RegisterHeartbeatListeners()
 
@@ -701,6 +703,26 @@ func (container *Container) MessageThreadHandlerValidator() (validator *validato
 	)
 }
 
+// ContactHandlerValidator creates a new instance of validators.ContactHandlerValidator
+func (container *Container) ContactHandlerValidator() (validator *validators.ContactHandlerValidator) {
+	container.logger.Debug(fmt.Sprintf("creating %T", validator))
+	return validators.NewContactHandlerValidator(
+		container.Logger(),
+		container.Tracer(),
+	)
+}
+
+// ContactHandler creates a new instance of handlers.ContactHandler
+func (container *Container) ContactHandler() (h *handlers.ContactHandler) {
+	container.logger.Debug(fmt.Sprintf("creating %T", h))
+	return handlers.NewContactHandler(
+		container.Logger(),
+		container.Tracer(),
+		container.ContactHandlerValidator(),
+		container.ContactService(),
+	)
+}
+
 // PhoneHandlerValidator creates a new instance of validators.PhoneHandlerValidator
 func (container *Container) PhoneHandlerValidator() (validator *validators.PhoneHandlerValidator) {
 	container.logger.Debug(fmt.Sprintf("creating %T", validator))
@@ -899,6 +921,16 @@ func (container *Container) MessageThreadRepository() (repository repositories.M
 	)
 }
 
+// ContactRepository creates a new instance of repositories.ContactRepository
+func (container *Container) ContactRepository() (repository repositories.ContactRepository) {
+	container.logger.Debug("creating GORM repositories.ContactRepository")
+	return repositories.NewGormContactRepository(
+		container.Logger(),
+		container.Tracer(),
+		container.DB(),
+	)
+}
+
 // HeartbeatMonitorRepository creates a new instance of repositories.HeartbeatMonitorRepository
 func (container *Container) HeartbeatMonitorRepository() (repository repositories.HeartbeatMonitorRepository) {
 	switch os.Getenv("HEARTBEAT_DB_BACKEND") {
@@ -1114,7 +1146,18 @@ func (container *Container) MessageThreadService() (service *services.MessageThr
 		container.MessageThreadRepository(),
 		container.PhoneRepository(),
 		container.EventDispatcher(),
-		nil,
+		container.ContactService(),
+	)
+}
+
+// ContactService creates a new instance of services.ContactService
+func (container *Container) ContactService() (service *services.ContactService) {
+	container.logger.Debug(fmt.Sprintf("creating %T", service))
+	return services.NewContactService(
+		container.Logger(),
+		container.Tracer(),
+		container.ContactRepository(),
+		container.Cache(),
 	)
 }
 
@@ -1669,6 +1712,12 @@ func (container *Container) RegisterMessageThreadRoutes() {
 	container.MessageThreadHandler().RegisterRoutes(container.App(), container.AuthenticatedMiddleware())
 }
 
+// RegisterContactRoutes registers routes for the /contacts prefix
+func (container *Container) RegisterContactRoutes() {
+	container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.ContactHandler{}))
+	container.ContactHandler().RegisterRoutes(container.App(), container.AuthenticatedMiddleware())
+}
+
 // RegisterHeartbeatRoutes registers routes for the /heartbeats prefix
 func (container *Container) RegisterHeartbeatRoutes() {
 	container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.HeartbeatHandler{}))
diff --git a/api/pkg/handlers/contact_handler.go b/api/pkg/handlers/contact_handler.go
new file mode 100644
index 000000000..94e627eb4
--- /dev/null
+++ b/api/pkg/handlers/contact_handler.go
@@ -0,0 +1,274 @@
+package handlers
+
+import (
+	"fmt"
+
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/requests"
+	"github.com/NdoleStudio/httpsms/pkg/services"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/httpsms/pkg/validators"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/davecgh/go-spew/spew"
+	"github.com/gofiber/fiber/v3"
+	"github.com/google/uuid"
+)
+
+// ContactHandler handles contact http requests.
+type ContactHandler struct {
+	handler
+	logger    telemetry.Logger
+	tracer    telemetry.Tracer
+	validator *validators.ContactHandlerValidator
+	service   *services.ContactService
+}
+
+// NewContactHandler creates a new ContactHandler.
+func NewContactHandler(
+	logger telemetry.Logger,
+	tracer telemetry.Tracer,
+	validator *validators.ContactHandlerValidator,
+	service *services.ContactService,
+) (h *ContactHandler) {
+	return &ContactHandler{
+		logger:    logger.WithService(fmt.Sprintf("%T", h)),
+		tracer:    tracer,
+		validator: validator,
+		service:   service,
+	}
+}
+
+// RegisterRoutes registers the routes for the ContactHandler.
+func (h *ContactHandler) RegisterRoutes(router fiber.Router, middlewares ...fiber.Handler) {
+	h.register(router, fiber.MethodGet, "/v1/contacts", middlewares, h.Index)
+	h.register(router, fiber.MethodPost, "/v1/contacts", middlewares, h.Store)
+	h.register(router, fiber.MethodPost, "/v1/contacts/upload", middlewares, h.Upload)
+	h.register(router, fiber.MethodPut, "/v1/contacts/:contactID", middlewares, h.Update)
+	h.register(router, fiber.MethodDelete, "/v1/contacts/:contactID", middlewares, h.Delete)
+}
+
+// Index lists contacts for the authenticated user.
+// @Summary      List contacts
+// @Description  Returns the paginated list of contacts for the authenticated user.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param        skip	query  int  	false	"number of contacts to skip"	minimum(0)
+// @Param        query	query  string  	false 	"filter contacts containing query"
+// @Param        limit	query  int  	false	"number of contacts to return"	minimum(1)	maximum(100)
+// @Success      200 	{object}	responses.ContactsResponse
+// @Failure      400	{object}	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure      422	{object}	responses.UnprocessableEntity
+// @Failure      500	{object}	responses.InternalServerError
+// @Router       /contacts [get]
+func (h *ContactHandler) Index(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	var request requests.ContactIndex
+	if err := c.Bind().Query(&request); err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall params [%s] into %T", c.OriginalURL(), request))
+		return h.responseBadRequest(c, err)
+	}
+
+	sanitized := request.Sanitize()
+	if errors := h.validator.ValidateIndex(ctx, sanitized); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while listing contacts [%+#v]", spew.Sdump(errors), sanitized))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while listing contacts")
+	}
+
+	userID := h.userIDFomContext(c)
+	contacts, err := h.service.Index(ctx, userID, sanitized.ToIndexParams())
+	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)
+}
+
+// Store creates one or many contacts.
+// @Summary      Create one or many contacts
+// @Description  Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a "contacts" array.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param        payload   body 		requests.ContactStoreRequest 	true 	"Contact(s) to create"
+// @Success      201 	{object}	responses.ContactsResponse
+// @Failure      400	{object}	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure      422	{object}	responses.UnprocessableEntity
+// @Failure      500	{object}	responses.InternalServerError
+// @Router       /contacts [post]
+func (h *ContactHandler) Store(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	var request requests.ContactStoreRequest
+	if err := c.Bind().Body(&request); err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body [%s] into %T", c.Body(), request))
+		return h.responseBadRequest(c, err)
+	}
+
+	sanitized := request.Sanitize()
+	if errors := h.validator.ValidateStore(ctx, sanitized); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while creating contacts", spew.Sdump(errors)))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while creating contacts")
+	}
+
+	userID := h.userIDFomContext(c)
+	contacts := sanitized.ToContacts(userID)
+	if err := h.service.CreateMany(ctx, userID, contacts); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot create [%d] contacts for user [%s]", len(contacts), userID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseCreated(c, fmt.Sprintf("created %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)
+}
+
+// Upload imports contacts from a CSV file.
+// @Summary      Import contacts from CSV
+// @Description  Uploads a CSV file (multipart field "document") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by ";").
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       multipart/form-data
+// @Produce      json
+// @Param        document	formData	file	true	"CSV file of contacts"
+// @Success      201 	{object}	responses.ContactsResponse
+// @Failure      400	{object}	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure      422	{object}	responses.UnprocessableEntity
+// @Failure      500	{object}	responses.InternalServerError
+// @Router       /contacts/upload [post]
+func (h *ContactHandler) Upload(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	file, err := c.FormFile("document")
+	if err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot fetch file with name [%s] from request", "document"))
+		return h.responseBadRequest(c, err)
+	}
+
+	userID := h.userIDFomContext(c)
+	items, errors := h.validator.ValidateUpload(ctx, userID, file)
+	if len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while importing contacts from CSV [%s]", spew.Sdump(errors), file.Filename))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while importing contacts")
+	}
+
+	request := (requests.ContactStoreRequest{Contacts: items}).Sanitize()
+	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))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseCreated(c, fmt.Sprintf("imported %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)
+}
+
+// Update updates a single contact.
+// @Summary      Update a contact
+// @Description  Updates the details of a single contact.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param 		 contactID	path		string 							true 	"ID of the contact"
+// @Param        payload   	body 		requests.ContactUpdateRequest 	true 	"Contact details to update"
+// @Success      200 		{object}	responses.ContactResponse
+// @Failure      400		{object}	responses.BadRequest
+// @Failure 	 401    	{object}	responses.Unauthorized
+// @Failure      404		{object}	responses.NotFound
+// @Failure      422		{object}	responses.UnprocessableEntity
+// @Failure      500		{object}	responses.InternalServerError
+// @Router       /contacts/{contactID} [put]
+func (h *ContactHandler) Update(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	contactID := c.Params("contactID")
+	if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")
+	}
+
+	var request requests.ContactUpdateRequest
+	if err := c.Bind().Body(&request); err != nil {
+		ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body into %T", request))
+		return h.responseBadRequest(c, err)
+	}
+
+	sanitized := request.Sanitize()
+	if errors := h.validator.ValidateUpdate(ctx, sanitized); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")
+	}
+
+	userID := h.userIDFomContext(c)
+	contact, err := h.service.Get(ctx, userID, uuid.MustParse(contactID))
+	if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {
+		return h.responseNotFound(c, fmt.Sprintf("cannot find contact with ID [%s]", contactID))
+	}
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot load contact [%s] for user [%s]", contactID, userID))
+		return h.responseInternalServerError(c)
+	}
+
+	sanitized.ApplyTo(contact)
+	if err = h.service.Update(ctx, contact); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot update contact [%s] for user [%s]", contactID, userID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseOK(c, "contact updated successfully", contact)
+}
+
+// Delete removes a single contact.
+// @Summary      Delete a contact
+// @Description  Deletes a single contact from the database.
+// @Security	 ApiKeyAuth
+// @Tags         Contacts
+// @Accept       json
+// @Produce      json
+// @Param 		 contactID	path		string 	true	"ID of the contact"
+// @Success      204  	{object} 	responses.NoContent
+// @Failure      400  	{object}  	responses.BadRequest
+// @Failure 	 401    {object}	responses.Unauthorized
+// @Failure 	 404	{object}	responses.NotFound
+// @Failure      422  	{object} 	responses.UnprocessableEntity
+// @Failure      500  	{object}  	responses.InternalServerError
+// @Router       /contacts/{contactID} [delete]
+func (h *ContactHandler) Delete(c fiber.Ctx) error {
+	ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
+	defer span.End()
+
+	contactID := c.Params("contactID")
+	if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {
+		ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while deleting contact [%s]", spew.Sdump(errors), contactID))
+		return h.responseUnprocessableEntity(c, errors, "validation errors while deleting contact")
+	}
+
+	userID := h.userIDFomContext(c)
+
+	// Load first so a missing contact for the authenticated user returns 404
+	// instead of silently succeeding via a 0-row DELETE. This also prevents
+	// leaking whether another user's contact exists.
+	if _, err := h.service.Get(ctx, userID, uuid.MustParse(contactID)); err != nil {
+		if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {
+			return h.responseNotFound(c, fmt.Sprintf("cannot find contact with ID [%s]", contactID))
+		}
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot load contact [%s] for user [%s]", contactID, userID))
+		return h.responseInternalServerError(c)
+	}
+
+	if err := h.service.Delete(ctx, userID, uuid.MustParse(contactID)); err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))
+		return h.responseInternalServerError(c)
+	}
+
+	return h.responseNoContent(c, "contact deleted successfully")
+}
diff --git a/api/pkg/handlers/contact_handler_test.go b/api/pkg/handlers/contact_handler_test.go
new file mode 100644
index 000000000..097ce1b2b
--- /dev/null
+++ b/api/pkg/handlers/contact_handler_test.go
@@ -0,0 +1,509 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"net/textproto"
+	"net/url"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/NdoleStudio/httpsms/pkg/cache"
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/middlewares"
+	"github.com/NdoleStudio/httpsms/pkg/repositories"
+	"github.com/NdoleStudio/httpsms/pkg/services"
+	"github.com/NdoleStudio/httpsms/pkg/telemetry"
+	"github.com/NdoleStudio/httpsms/pkg/validators"
+	"github.com/NdoleStudio/stacktrace"
+	"github.com/gofiber/fiber/v3"
+	"github.com/google/uuid"
+	"github.com/lib/pq"
+	ttlCache "github.com/patrickmn/go-cache"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+// contactHandlerFakeRepo is a shared, thread-safe ContactRepository stub that
+// records the effects of Store/Update/Delete and returns configurable Load/Index
+// results so handler tests can assert real service→repository behaviour.
+type contactHandlerFakeRepo struct {
+	mu sync.Mutex
+
+	stored      [][]*entities.Contact
+	updated     []*entities.Contact
+	deleted     []deletedContact
+	indexParams []repositories.IndexParams
+	loadCalls   []loadedContact
+
+	loadResult  *entities.Contact
+	loadErr     error
+	indexResult []entities.Contact
+	indexErr    error
+	storeErr    error
+	updateErr   error
+	deleteErr   error
+}
+
+type deletedContact struct {
+	userID entities.UserID
+	id     uuid.UUID
+}
+
+type loadedContact struct {
+	userID entities.UserID
+	id     uuid.UUID
+}
+
+func (r *contactHandlerFakeRepo) Store(_ context.Context, contacts []*entities.Contact) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.storeErr != nil {
+		return r.storeErr
+	}
+	r.stored = append(r.stored, contacts)
+	return nil
+}
+
+func (r *contactHandlerFakeRepo) Update(_ context.Context, contact *entities.Contact) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.updated = append(r.updated, contact)
+	return nil
+}
+
+func (r *contactHandlerFakeRepo) Load(_ context.Context, userID entities.UserID, id uuid.UUID) (*entities.Contact, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.loadCalls = append(r.loadCalls, loadedContact{userID: userID, id: id})
+	if r.loadErr != nil {
+		return nil, r.loadErr
+	}
+	if r.loadResult == nil {
+		return nil, nil
+	}
+	// Return a copy so handler mutations don't corrupt the fixture.
+	clone := *r.loadResult
+	return &clone, nil
+}
+
+func (r *contactHandlerFakeRepo) Index(_ context.Context, _ entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.indexParams = append(r.indexParams, params)
+	if r.indexErr != nil {
+		return nil, r.indexErr
+	}
+	out := make([]entities.Contact, len(r.indexResult))
+	copy(out, r.indexResult)
+	return &out, nil
+}
+
+func (r *contactHandlerFakeRepo) FetchAll(context.Context, entities.UserID) (*[]entities.Contact, error) {
+	out := []entities.Contact{}
+	return &out, nil
+}
+
+func (r *contactHandlerFakeRepo) Delete(_ context.Context, userID entities.UserID, id uuid.UUID) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.deleted = append(r.deleted, deletedContact{userID: userID, id: id})
+	return nil
+}
+
+func (r *contactHandlerFakeRepo) DeleteAllForUser(context.Context, entities.UserID) error {
+	return nil
+}
+
+// snapshot returns a safe read of the recorded effects.
+func (r *contactHandlerFakeRepo) snapshot() ([][]*entities.Contact, []*entities.Contact, []deletedContact, []repositories.IndexParams) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.stored, r.updated, r.deleted, r.indexParams
+}
+
+const contactHandlerTestUserID = entities.UserID("user-id")
+
+func newContactHandlerTestApp(repo repositories.ContactRepository) *fiber.App {
+	logger := &messageThreadHandlerNoopLogger{}
+	tracer := telemetry.NewOtelLogger("test", logger)
+	appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))
+	service := services.NewContactService(logger, tracer, repo, appCache)
+	handler := NewContactHandler(logger, tracer, validators.NewContactHandlerValidator(logger, tracer), service)
+
+	app := fiber.New()
+	app.Use(func(c fiber.Ctx) error {
+		c.Locals(middlewares.ContextKeyAuthUserID, entities.AuthContext{ID: contactHandlerTestUserID, Email: "user@example.com"})
+		return c.Next()
+	})
+	handler.RegisterRoutes(app)
+	return app
+}
+
+type contactHandlerPayload struct {
+	Status  string          `json:"status"`
+	Message string          `json:"message"`
+	Data    json.RawMessage `json:"data"`
+}
+
+func decodeContactHandlerPayload(t *testing.T, resp *http.Response) contactHandlerPayload {
+	t.Helper()
+	var payload contactHandlerPayload
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&payload))
+	return payload
+}
+
+func TestContactHandler_Store_CreatesSingleContact(t *testing.T) {
+	repo := &contactHandlerFakeRepo{}
+	app := newContactHandlerTestApp(repo)
+
+	body := `[{"name":"Alice","phone_numbers":["+18005550199"],"emails":["alice@example.com"]}]`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusCreated, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	require.Len(t, stored, 1)
+	require.Len(t, stored[0], 1)
+	require.Equal(t, "Alice", stored[0][0].Name)
+	require.Equal(t, contactHandlerTestUserID, stored[0][0].UserID)
+	require.Equal(t, pq.StringArray{"+18005550199"}, stored[0][0].PhoneNumbers)
+}
+
+func TestContactHandler_Store_CreatesManyContactsFromObjectShape(t *testing.T) {
+	repo := &contactHandlerFakeRepo{}
+	app := newContactHandlerTestApp(repo)
+
+	body := `{"contacts":[
+		{"name":"Alice","phone_numbers":["+18005550199"]},
+		{"name":"Bob","phone_numbers":["+18005550100"]}
+	]}`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusCreated, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	require.Len(t, stored, 1)
+	require.Len(t, stored[0], 2)
+	assert.Equal(t, "Alice", stored[0][0].Name)
+	assert.Equal(t, "Bob", stored[0][1].Name)
+}
+
+func TestContactHandler_Store_ValidationError_ReturnsUnprocessableEntity(t *testing.T) {
+	repo := &contactHandlerFakeRepo{}
+	app := newContactHandlerTestApp(repo)
+
+	body := `[{"name":"","phone_numbers":[]}]`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	require.Empty(t, stored, "no contact should be stored on validation failure")
+}
+
+func TestContactHandler_Store_MalformedJSON_ReturnsBadRequest(t *testing.T) {
+	app := newContactHandlerTestApp(&contactHandlerFakeRepo{})
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString("{not json"))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusBadRequest, resp.StatusCode)
+}
+
+func buildContactCSVUpload(t *testing.T, filename string, contentType string, body string) (*bytes.Buffer, string) {
+	t.Helper()
+	var buf bytes.Buffer
+	writer := multipart.NewWriter(&buf)
+
+	header := make(textproto.MIMEHeader)
+	header.Set("Content-Disposition", fmt.Sprintf(`form-data; name="document"; filename="%s"`, filename))
+	header.Set("Content-Type", contentType)
+	part, err := writer.CreatePart(header)
+	require.NoError(t, err)
+	_, err = part.Write([]byte(body))
+	require.NoError(t, err)
+	require.NoError(t, writer.Close())
+	return &buf, writer.FormDataContentType()
+}
+
+func TestContactHandler_Upload_CSVSuccess(t *testing.T) {
+	repo := &contactHandlerFakeRepo{}
+	app := newContactHandlerTestApp(repo)
+
+	csv := "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199\nBob,,+18005550100\n"
+	body, contentType := buildContactCSVUpload(t, "contacts.csv", "text/csv", csv)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", body)
+	req.Header.Set("Content-Type", contentType)
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusCreated, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	require.Len(t, stored, 1)
+	require.Len(t, stored[0], 2)
+	assert.Equal(t, "Alice", stored[0][0].Name)
+	assert.Equal(t, "Bob", stored[0][1].Name)
+	for _, c := range stored[0] {
+		assert.Equal(t, contactHandlerTestUserID, c.UserID)
+	}
+}
+
+func TestContactHandler_Upload_NonCSVFile_ReturnsUnprocessableEntity(t *testing.T) {
+	repo := &contactHandlerFakeRepo{}
+	app := newContactHandlerTestApp(repo)
+
+	body, contentType := buildContactCSVUpload(t, "contacts.txt", "text/plain", "junk")
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", body)
+	req.Header.Set("Content-Type", contentType)
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	require.Empty(t, stored)
+}
+
+func TestContactHandler_Upload_MissingDocument_ReturnsBadRequest(t *testing.T) {
+	app := newContactHandlerTestApp(&contactHandlerFakeRepo{})
+
+	// multipart body without the "document" field.
+	var buf bytes.Buffer
+	writer := multipart.NewWriter(&buf)
+	require.NoError(t, writer.WriteField("other", "value"))
+	require.NoError(t, writer.Close())
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", &buf)
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusBadRequest, resp.StatusCode)
+}
+
+func TestContactHandler_Update_Success(t *testing.T) {
+	contactID := uuid.New()
+	repo := &contactHandlerFakeRepo{
+		loadResult: &entities.Contact{
+			ID:           contactID,
+			UserID:       contactHandlerTestUserID,
+			Name:         "Old Name",
+			PhoneNumbers: pq.StringArray{"+18005550100"},
+		},
+	}
+	app := newContactHandlerTestApp(repo)
+
+	body := `{"name":"New Name","phone_numbers":["+18005550199"],"emails":["new@example.com"]}`
+	req := httptest.NewRequest(http.MethodPut, "/v1/contacts/"+contactID.String(), bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	_, updated, _, _ := repo.snapshot()
+	require.Len(t, updated, 1)
+	assert.Equal(t, "New Name", updated[0].Name)
+	assert.Equal(t, contactID, updated[0].ID)
+	assert.Equal(t, contactHandlerTestUserID, updated[0].UserID)
+	assert.Equal(t, pq.StringArray{"+18005550199"}, updated[0].PhoneNumbers)
+
+	// The repo Load call must have been user-scoped.
+	require.Len(t, repo.loadCalls, 1)
+	assert.Equal(t, contactHandlerTestUserID, repo.loadCalls[0].userID)
+	assert.Equal(t, contactID, repo.loadCalls[0].id)
+}
+
+func TestContactHandler_Update_NotFound_ReturnsNotFound(t *testing.T) {
+	contactID := uuid.New()
+	repo := &contactHandlerFakeRepo{
+		loadErr: stacktrace.PropagateWithCodef(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found"),
+	}
+	app := newContactHandlerTestApp(repo)
+
+	body := `{"name":"New Name","phone_numbers":["+18005550199"]}`
+	req := httptest.NewRequest(http.MethodPut, "/v1/contacts/"+contactID.String(), bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+	payload := decodeContactHandlerPayload(t, resp)
+	assert.Contains(t, payload.Message, contactID.String())
+
+	_, updated, _, _ := repo.snapshot()
+	assert.Empty(t, updated)
+}
+
+func TestContactHandler_Update_InvalidID_ReturnsUnprocessableEntity(t *testing.T) {
+	app := newContactHandlerTestApp(&contactHandlerFakeRepo{})
+
+	body := `{"name":"Alice","phone_numbers":["+18005550199"]}`
+	req := httptest.NewRequest(http.MethodPut, "/v1/contacts/not-a-uuid", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+}
+
+func TestContactHandler_Update_ValidationError_ReturnsUnprocessableEntity(t *testing.T) {
+	contactID := uuid.New()
+	app := newContactHandlerTestApp(&contactHandlerFakeRepo{})
+
+	body := `{"name":"","phone_numbers":[]}`
+	req := httptest.NewRequest(http.MethodPut, "/v1/contacts/"+contactID.String(), bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+}
+
+func TestContactHandler_Delete_Success(t *testing.T) {
+	contactID := uuid.New()
+	repo := &contactHandlerFakeRepo{
+		loadResult: &entities.Contact{
+			ID:     contactID,
+			UserID: contactHandlerTestUserID,
+			Name:   "Alice",
+		},
+	}
+	app := newContactHandlerTestApp(repo)
+
+	req := httptest.NewRequest(http.MethodDelete, "/v1/contacts/"+contactID.String(), nil)
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusNoContent, resp.StatusCode)
+
+	_, _, deleted, _ := repo.snapshot()
+	require.Len(t, deleted, 1)
+	assert.Equal(t, contactHandlerTestUserID, deleted[0].userID)
+	assert.Equal(t, contactID, deleted[0].id)
+}
+
+func TestContactHandler_Delete_NotFound_ReturnsNotFound(t *testing.T) {
+	contactID := uuid.New()
+	repo := &contactHandlerFakeRepo{
+		loadErr: stacktrace.PropagateWithCodef(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found"),
+	}
+	app := newContactHandlerTestApp(repo)
+
+	req := httptest.NewRequest(http.MethodDelete, "/v1/contacts/"+contactID.String(), nil)
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+	// Ensure we did not delete another user's contact silently.
+	_, _, deleted, _ := repo.snapshot()
+	assert.Empty(t, deleted)
+}
+
+func TestContactHandler_Delete_InvalidID_ReturnsUnprocessableEntity(t *testing.T) {
+	app := newContactHandlerTestApp(&contactHandlerFakeRepo{})
+
+	req := httptest.NewRequest(http.MethodDelete, "/v1/contacts/not-a-uuid", nil)
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+}
+
+func TestContactHandler_Index_ConvertsQueryAndScopesToUser(t *testing.T) {
+	repo := &contactHandlerFakeRepo{
+		indexResult: []entities.Contact{
+			{ID: uuid.New(), UserID: contactHandlerTestUserID, Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},
+		},
+	}
+	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)
+
+	_, _, _, indexParams := repo.snapshot()
+	require.Len(t, indexParams, 1)
+	assert.Equal(t, 5, indexParams[0].Skip)
+	assert.Equal(t, 25, indexParams[0].Limit)
+	assert.Equal(t, "ali", indexParams[0].Query)
+
+	payload := decodeContactHandlerPayload(t, resp)
+	assert.Equal(t, "success", payload.Status)
+	assert.Contains(t, payload.Message, "1")
+}
+
+func TestContactHandler_Index_DefaultsAppliedWhenParamsMissing(t *testing.T) {
+	repo := &contactHandlerFakeRepo{}
+	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.StatusOK, resp.StatusCode)
+
+	_, _, _, indexParams := repo.snapshot()
+	require.Len(t, indexParams, 1)
+	assert.Equal(t, 0, indexParams[0].Skip)
+	assert.Equal(t, 20, indexParams[0].Limit)
+	assert.Equal(t, "", indexParams[0].Query)
+}
+
+func TestContactHandler_Index_InvalidLimit_ReturnsUnprocessableEntity(t *testing.T) {
+	app := newContactHandlerTestApp(&contactHandlerFakeRepo{})
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/contacts?limit=notanumber", nil)
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)
+}
+
+// TestContactService_WiresIntoMessageThreadService is a compile-time guard that
+// pins the DI wiring change: ContactService must satisfy the contactMapProvider
+// interface consumed by MessageThreadService, so container.MessageThreadService()
+// can be constructed with container.ContactService() instead of nil.
+func TestContactService_WiresIntoMessageThreadService(t *testing.T) {
+	logger := &messageThreadHandlerNoopLogger{}
+	tracer := telemetry.NewOtelLogger("test", logger)
+	appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))
+	contactService := services.NewContactService(logger, tracer, &contactHandlerFakeRepo{}, appCache)
+
+	// If this compiles and runs, the ContactService satisfies the
+	// contactMapProvider interface expected by NewMessageThreadService.
+	threadService := services.NewMessageThreadService(logger, tracer, nil, nil, nil, contactService)
+	require.NotNil(t, threadService)
+}

From d835053e7c8d3b300a42fa28abcf64de77232ebf Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 23:04:17 +0300
Subject: [PATCH 13/24] chore(api): regenerate contacts swagger

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/docs/docs.go                          | 463 ++++++++++++++++++++++
 api/docs/swagger.json                     | 463 ++++++++++++++++++++++
 api/docs/swagger.yaml                     | 307 ++++++++++++++
 api/pkg/responses/contact_responses.go    |  15 +
 web/public/templates/httpsms-contacts.csv |   4 +
 5 files changed, 1252 insertions(+)
 create mode 100644 api/pkg/responses/contact_responses.go
 create mode 100644 web/public/templates/httpsms-contacts.csv

diff --git a/api/docs/docs.go b/api/docs/docs.go
index 41653fafc..c8ea80628 100644
--- a/api/docs/docs.go
+++ b/api/docs/docs.go
@@ -242,6 +242,344 @@ const docTemplate = `{
                 }
             }
         },
+        "/contacts": {
+            "get": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Returns the paginated list of contacts for the authenticated user.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "List contacts",
+                "parameters": [
+                    {
+                        "minimum": 0,
+                        "type": "integer",
+                        "description": "number of contacts to skip",
+                        "name": "skip",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "filter contacts containing query",
+                        "name": "query",
+                        "in": "query"
+                    },
+                    {
+                        "maximum": 100,
+                        "minimum": 1,
+                        "type": "integer",
+                        "description": "number of contacts to return",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a \"contacts\" array.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Create one or many contacts",
+                "parameters": [
+                    {
+                        "description": "Contact(s) to create",
+                        "name": "payload",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/requests.ContactStoreRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            }
+        },
+        "/contacts/upload": {
+            "post": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Uploads a CSV file (multipart field \"document\") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by \";\").",
+                "consumes": [
+                    "multipart/form-data"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Import contacts from CSV",
+                "parameters": [
+                    {
+                        "type": "file",
+                        "description": "CSV file of contacts",
+                        "name": "document",
+                        "in": "formData",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            }
+        },
+        "/contacts/{contactID}": {
+            "put": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Updates the details of a single contact.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update a contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ID of the contact",
+                        "name": "contactID",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Contact details to update",
+                        "name": "payload",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/requests.ContactUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/responses.NotFound"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Deletes a single contact from the database.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Delete a contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ID of the contact",
+                        "name": "contactID",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content",
+                        "schema": {
+                            "$ref": "#/definitions/responses.NoContent"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/responses.NotFound"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            }
+        },
         "/discord-integrations": {
             "get": {
                 "security": [
@@ -4154,6 +4492,86 @@ const docTemplate = `{
                 }
             }
         },
+        "requests.ContactItem": {
+            "type": "object",
+            "required": [
+                "emails",
+                "name",
+                "phone_numbers",
+                "properties"
+            ],
+            "properties": {
+                "emails": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Alice Smith"
+                },
+                "phone_numbers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "properties": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "requests.ContactStoreRequest": {
+            "type": "object",
+            "required": [
+                "contacts"
+            ],
+            "properties": {
+                "contacts": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/requests.ContactItem"
+                    }
+                }
+            }
+        },
+        "requests.ContactUpdateRequest": {
+            "type": "object",
+            "required": [
+                "emails",
+                "name",
+                "phone_numbers",
+                "properties"
+            ],
+            "properties": {
+                "emails": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Alice Smith"
+                },
+                "phone_numbers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "properties": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
         "requests.DiscordStore": {
             "type": "object",
             "required": [
@@ -4817,6 +5235,51 @@ const docTemplate = `{
                 }
             }
         },
+        "responses.ContactResponse": {
+            "type": "object",
+            "required": [
+                "data",
+                "message",
+                "status"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/entities.Contact"
+                },
+                "message": {
+                    "type": "string",
+                    "example": "Request handled successfully"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "success"
+                }
+            }
+        },
+        "responses.ContactsResponse": {
+            "type": "object",
+            "required": [
+                "data",
+                "message",
+                "status"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/entities.Contact"
+                    }
+                },
+                "message": {
+                    "type": "string",
+                    "example": "Request handled successfully"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "success"
+                }
+            }
+        },
         "responses.DiscordResponse": {
             "type": "object",
             "required": [
diff --git a/api/docs/swagger.json b/api/docs/swagger.json
index 3f70ef926..b605cfa8f 100644
--- a/api/docs/swagger.json
+++ b/api/docs/swagger.json
@@ -239,6 +239,344 @@
                 }
             }
         },
+        "/contacts": {
+            "get": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Returns the paginated list of contacts for the authenticated user.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "List contacts",
+                "parameters": [
+                    {
+                        "minimum": 0,
+                        "type": "integer",
+                        "description": "number of contacts to skip",
+                        "name": "skip",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "filter contacts containing query",
+                        "name": "query",
+                        "in": "query"
+                    },
+                    {
+                        "maximum": 100,
+                        "minimum": 1,
+                        "type": "integer",
+                        "description": "number of contacts to return",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a \"contacts\" array.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Create one or many contacts",
+                "parameters": [
+                    {
+                        "description": "Contact(s) to create",
+                        "name": "payload",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/requests.ContactStoreRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            }
+        },
+        "/contacts/upload": {
+            "post": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Uploads a CSV file (multipart field \"document\") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by \";\").",
+                "consumes": [
+                    "multipart/form-data"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Import contacts from CSV",
+                "parameters": [
+                    {
+                        "type": "file",
+                        "description": "CSV file of contacts",
+                        "name": "document",
+                        "in": "formData",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            }
+        },
+        "/contacts/{contactID}": {
+            "put": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Updates the details of a single contact.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update a contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ID of the contact",
+                        "name": "contactID",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Contact details to update",
+                        "name": "payload",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/requests.ContactUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/responses.ContactResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/responses.NotFound"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "security": [
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "Deletes a single contact from the database.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Delete a contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ID of the contact",
+                        "name": "contactID",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content",
+                        "schema": {
+                            "$ref": "#/definitions/responses.NoContent"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/responses.BadRequest"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/responses.Unauthorized"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/responses.NotFound"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/responses.UnprocessableEntity"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/responses.InternalServerError"
+                        }
+                    }
+                }
+            }
+        },
         "/discord-integrations": {
             "get": {
                 "security": [
@@ -4151,6 +4489,86 @@
                 }
             }
         },
+        "requests.ContactItem": {
+            "type": "object",
+            "required": [
+                "emails",
+                "name",
+                "phone_numbers",
+                "properties"
+            ],
+            "properties": {
+                "emails": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Alice Smith"
+                },
+                "phone_numbers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "properties": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "requests.ContactStoreRequest": {
+            "type": "object",
+            "required": [
+                "contacts"
+            ],
+            "properties": {
+                "contacts": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/requests.ContactItem"
+                    }
+                }
+            }
+        },
+        "requests.ContactUpdateRequest": {
+            "type": "object",
+            "required": [
+                "emails",
+                "name",
+                "phone_numbers",
+                "properties"
+            ],
+            "properties": {
+                "emails": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Alice Smith"
+                },
+                "phone_numbers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "properties": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
         "requests.DiscordStore": {
             "type": "object",
             "required": [
@@ -4814,6 +5232,51 @@
                 }
             }
         },
+        "responses.ContactResponse": {
+            "type": "object",
+            "required": [
+                "data",
+                "message",
+                "status"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/entities.Contact"
+                },
+                "message": {
+                    "type": "string",
+                    "example": "Request handled successfully"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "success"
+                }
+            }
+        },
+        "responses.ContactsResponse": {
+            "type": "object",
+            "required": [
+                "data",
+                "message",
+                "status"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/entities.Contact"
+                    }
+                },
+                "message": {
+                    "type": "string",
+                    "example": "Request handled successfully"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "success"
+                }
+            }
+        },
         "responses.DiscordResponse": {
             "type": "object",
             "required": [
diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yaml
index a83c943fd..75016daa7 100644
--- a/api/docs/swagger.yaml
+++ b/api/docs/swagger.yaml
@@ -653,6 +653,61 @@ definitions:
     - url
     - user_id
     type: object
+  requests.ContactItem:
+    properties:
+      emails:
+        items:
+          type: string
+        type: array
+      name:
+        example: Alice Smith
+        type: string
+      phone_numbers:
+        items:
+          type: string
+        type: array
+      properties:
+        additionalProperties:
+          type: string
+        type: object
+    required:
+    - emails
+    - name
+    - phone_numbers
+    - properties
+    type: object
+  requests.ContactStoreRequest:
+    properties:
+      contacts:
+        items:
+          $ref: '#/definitions/requests.ContactItem'
+        type: array
+    required:
+    - contacts
+    type: object
+  requests.ContactUpdateRequest:
+    properties:
+      emails:
+        items:
+          type: string
+        type: array
+      name:
+        example: Alice Smith
+        type: string
+      phone_numbers:
+        items:
+          type: string
+        type: array
+      properties:
+        additionalProperties:
+          type: string
+        type: object
+    required:
+    - emails
+    - name
+    - phone_numbers
+    - properties
+    type: object
   requests.DiscordStore:
     properties:
       incoming_channel_id:
@@ -1157,6 +1212,38 @@ definitions:
     - message
     - status
     type: object
+  responses.ContactResponse:
+    properties:
+      data:
+        $ref: '#/definitions/entities.Contact'
+      message:
+        example: Request handled successfully
+        type: string
+      status:
+        example: success
+        type: string
+    required:
+    - data
+    - message
+    - status
+    type: object
+  responses.ContactsResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/entities.Contact'
+        type: array
+      message:
+        example: Request handled successfully
+        type: string
+      status:
+        example: success
+        type: string
+    required:
+    - data
+    - message
+    - status
+    type: object
   responses.DiscordResponse:
     properties:
       data:
@@ -1795,6 +1882,226 @@ paths:
       summary: Store bulk SMS file
       tags:
       - BulkSMS
+  /contacts:
+    get:
+      consumes:
+      - application/json
+      description: Returns the paginated list of contacts for the authenticated user.
+      parameters:
+      - description: number of contacts to skip
+        in: query
+        minimum: 0
+        name: skip
+        type: integer
+      - description: filter contacts containing query
+        in: query
+        name: query
+        type: string
+      - description: number of contacts to return
+        in: query
+        maximum: 100
+        minimum: 1
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/responses.ContactsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/responses.BadRequest'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/responses.Unauthorized'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/responses.UnprocessableEntity'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/responses.InternalServerError'
+      security:
+      - ApiKeyAuth: []
+      summary: List contacts
+      tags:
+      - Contacts
+    post:
+      consumes:
+      - application/json
+      description: Creates a single contact or a batch of contacts. Accepts a JSON
+        array or an object with a "contacts" array.
+      parameters:
+      - description: Contact(s) to create
+        in: body
+        name: payload
+        required: true
+        schema:
+          $ref: '#/definitions/requests.ContactStoreRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/responses.ContactsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/responses.BadRequest'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/responses.Unauthorized'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/responses.UnprocessableEntity'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/responses.InternalServerError'
+      security:
+      - ApiKeyAuth: []
+      summary: Create one or many contacts
+      tags:
+      - Contacts
+  /contacts/{contactID}:
+    delete:
+      consumes:
+      - application/json
+      description: Deletes a single contact from the database.
+      parameters:
+      - description: ID of the contact
+        in: path
+        name: contactID
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "204":
+          description: No Content
+          schema:
+            $ref: '#/definitions/responses.NoContent'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/responses.BadRequest'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/responses.Unauthorized'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/responses.NotFound'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/responses.UnprocessableEntity'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/responses.InternalServerError'
+      security:
+      - ApiKeyAuth: []
+      summary: Delete a contact
+      tags:
+      - Contacts
+    put:
+      consumes:
+      - application/json
+      description: Updates the details of a single contact.
+      parameters:
+      - description: ID of the contact
+        in: path
+        name: contactID
+        required: true
+        type: string
+      - description: Contact details to update
+        in: body
+        name: payload
+        required: true
+        schema:
+          $ref: '#/definitions/requests.ContactUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/responses.ContactResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/responses.BadRequest'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/responses.Unauthorized'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/responses.NotFound'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/responses.UnprocessableEntity'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/responses.InternalServerError'
+      security:
+      - ApiKeyAuth: []
+      summary: Update a contact
+      tags:
+      - Contacts
+  /contacts/upload:
+    post:
+      consumes:
+      - multipart/form-data
+      description: 'Uploads a CSV file (multipart field "document") of contacts. Columns:
+        Name, Emails, PhoneNumbers (multi-values separated by ";").'
+      parameters:
+      - description: CSV file of contacts
+        in: formData
+        name: document
+        required: true
+        type: file
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/responses.ContactsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/responses.BadRequest'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/responses.Unauthorized'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/responses.UnprocessableEntity'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/responses.InternalServerError'
+      security:
+      - ApiKeyAuth: []
+      summary: Import contacts from CSV
+      tags:
+      - Contacts
   /discord-integrations:
     get:
       consumes:
diff --git a/api/pkg/responses/contact_responses.go b/api/pkg/responses/contact_responses.go
new file mode 100644
index 000000000..e8f2a319a
--- /dev/null
+++ b/api/pkg/responses/contact_responses.go
@@ -0,0 +1,15 @@
+package responses
+
+import "github.com/NdoleStudio/httpsms/pkg/entities"
+
+// ContactResponse is the payload containing entities.Contact.
+type ContactResponse struct {
+	response
+	Data entities.Contact `json:"data"`
+}
+
+// ContactsResponse is the payload containing []entities.Contact.
+type ContactsResponse struct {
+	response
+	Data []entities.Contact `json:"data"`
+}
diff --git a/web/public/templates/httpsms-contacts.csv b/web/public/templates/httpsms-contacts.csv
new file mode 100644
index 000000000..8ba7c01d2
--- /dev/null
+++ b/web/public/templates/httpsms-contacts.csv
@@ -0,0 +1,4 @@
+Name,Emails,PhoneNumbers
+John Doe,john@example.com,+18005550199
+Jane Smith,jane@example.com;jane.work@example.com,+18005550100;+18005550111
+Acme Support,,+18005550122

From 5a2bd389c40b431562a2d042a6680b371dc9592e Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 23:15:38 +0300
Subject: [PATCH 14/24] fix(api): mark contact fields optional

Make emails/properties optional in contact request DTOs.
Regenerate Swagger docs and add request JSON regression tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/docs/docs.go                       |  8 ++------
 api/docs/swagger.json                  |  8 ++------
 api/docs/swagger.yaml                  |  4 ----
 api/pkg/requests/contact_store.go      |  4 ++--
 api/pkg/requests/contact_store_test.go | 28 ++++++++++++++++++++++++++
 api/pkg/requests/contact_update.go     |  4 ++--
 6 files changed, 36 insertions(+), 20 deletions(-)

diff --git a/api/docs/docs.go b/api/docs/docs.go
index c8ea80628..ce6103547 100644
--- a/api/docs/docs.go
+++ b/api/docs/docs.go
@@ -4495,10 +4495,8 @@ const docTemplate = `{
         "requests.ContactItem": {
             "type": "object",
             "required": [
-                "emails",
                 "name",
-                "phone_numbers",
-                "properties"
+                "phone_numbers"
             ],
             "properties": {
                 "emails": {
@@ -4542,10 +4540,8 @@ const docTemplate = `{
         "requests.ContactUpdateRequest": {
             "type": "object",
             "required": [
-                "emails",
                 "name",
-                "phone_numbers",
-                "properties"
+                "phone_numbers"
             ],
             "properties": {
                 "emails": {
diff --git a/api/docs/swagger.json b/api/docs/swagger.json
index b605cfa8f..1711970a2 100644
--- a/api/docs/swagger.json
+++ b/api/docs/swagger.json
@@ -4492,10 +4492,8 @@
         "requests.ContactItem": {
             "type": "object",
             "required": [
-                "emails",
                 "name",
-                "phone_numbers",
-                "properties"
+                "phone_numbers"
             ],
             "properties": {
                 "emails": {
@@ -4539,10 +4537,8 @@
         "requests.ContactUpdateRequest": {
             "type": "object",
             "required": [
-                "emails",
                 "name",
-                "phone_numbers",
-                "properties"
+                "phone_numbers"
             ],
             "properties": {
                 "emails": {
diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yaml
index 75016daa7..5898c3762 100644
--- a/api/docs/swagger.yaml
+++ b/api/docs/swagger.yaml
@@ -671,10 +671,8 @@ definitions:
           type: string
         type: object
     required:
-    - emails
     - name
     - phone_numbers
-    - properties
     type: object
   requests.ContactStoreRequest:
     properties:
@@ -703,10 +701,8 @@ definitions:
           type: string
         type: object
     required:
-    - emails
     - name
     - phone_numbers
-    - properties
     type: object
   requests.DiscordStore:
     properties:
diff --git a/api/pkg/requests/contact_store.go b/api/pkg/requests/contact_store.go
index 78025fbd6..52e310d7b 100644
--- a/api/pkg/requests/contact_store.go
+++ b/api/pkg/requests/contact_store.go
@@ -13,9 +13,9 @@ import (
 // ContactItem is a single contact in a create request.
 type ContactItem struct {
 	Name         string            `json:"name" example:"Alice Smith"`
-	Emails       []string          `json:"emails"`
+	Emails       []string          `json:"emails,omitempty"`
 	PhoneNumbers []string          `json:"phone_numbers"`
-	Properties   map[string]string `json:"properties"`
+	Properties   map[string]string `json:"properties,omitempty"`
 }
 
 // ContactStoreRequest creates one or many contacts.
diff --git a/api/pkg/requests/contact_store_test.go b/api/pkg/requests/contact_store_test.go
index 2efd67b91..f80e4e357 100644
--- a/api/pkg/requests/contact_store_test.go
+++ b/api/pkg/requests/contact_store_test.go
@@ -31,6 +31,21 @@ func TestContactStoreRequest_UnmarshalObjectForm(t *testing.T) {
 	assert.Equal(t, []string{"+18005550100"}, request.Contacts[0].PhoneNumbers)
 }
 
+func TestContactStoreRequest_UnmarshalMissingOptionalFields(t *testing.T) {
+	var request ContactStoreRequest
+
+	require.NoError(t, json.Unmarshal([]byte(`[{"name":"Alice","phone_numbers":["+18005550199"]}]`), &request))
+
+	require.Len(t, request.Contacts, 1)
+	assert.Nil(t, request.Contacts[0].Emails)
+	assert.Nil(t, request.Contacts[0].Properties)
+
+	sanitized := request.Sanitize()
+	require.Len(t, sanitized.Contacts, 1)
+	assert.NotNil(t, sanitized.Contacts[0].Properties)
+	assert.Empty(t, sanitized.Contacts[0].Properties)
+}
+
 func TestContactStoreRequest_UnmarshalMalformedJSON(t *testing.T) {
 	var request ContactStoreRequest
 
@@ -140,6 +155,19 @@ func TestContactUpdateRequest_InitializesNilProperties(t *testing.T) {
 	assert.Empty(t, request.Properties)
 }
 
+func TestContactUpdateRequest_UnmarshalMissingOptionalFields(t *testing.T) {
+	var request ContactUpdateRequest
+
+	require.NoError(t, json.Unmarshal([]byte(`{"name":"Alice","phone_numbers":["+18005550199"]}`), &request))
+
+	assert.Nil(t, request.Emails)
+	assert.Nil(t, request.Properties)
+
+	sanitized := request.Sanitize()
+	assert.NotNil(t, sanitized.Properties)
+	assert.Empty(t, sanitized.Properties)
+}
+
 func TestContactIndex_SanitizeUsesDefaultsAndToIndexParams(t *testing.T) {
 	request := ContactIndex{}
 
diff --git a/api/pkg/requests/contact_update.go b/api/pkg/requests/contact_update.go
index 67772669d..55e34d604 100644
--- a/api/pkg/requests/contact_update.go
+++ b/api/pkg/requests/contact_update.go
@@ -12,9 +12,9 @@ import (
 type ContactUpdateRequest struct {
 	request
 	Name         string            `json:"name" example:"Alice Smith"`
-	Emails       []string          `json:"emails"`
+	Emails       []string          `json:"emails,omitempty"`
 	PhoneNumbers []string          `json:"phone_numbers"`
-	Properties   map[string]string `json:"properties"`
+	Properties   map[string]string `json:"properties,omitempty"`
 }
 
 // Sanitize trims and normalizes the update request.

From 2c4e7d43f6ca0ed97b3e585bfc91e61a226f699c Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 23:19:15 +0300
Subject: [PATCH 15/24] chore(web): regenerate API models with Contact types

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/shared/types/api.ts | 56 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/web/shared/types/api.ts b/web/shared/types/api.ts
index 27e2db111..c32224525 100644
--- a/web/shared/types/api.ts
+++ b/web/shared/types/api.ts
@@ -71,6 +71,24 @@ export interface EntitiesBulkMessage {
   total: number;
 }
 
+export interface EntitiesContact {
+  /** @example "2022-06-05T14:26:02.302718+03:00" */
+  created_at: string;
+  /** @example ["alice@example.com"] */
+  emails: string[];
+  /** @example "32343a19-da5e-4b1b-a767-3298a73703cb" */
+  id: string;
+  /** @example "Alice Smith" */
+  name: string;
+  /** @example ["+18005550199","+18005550100"] */
+  phone_numbers: string[];
+  properties: Record<string, string>;
+  /** @example "2022-06-05T14:26:02.302718+03:00" */
+  updated_at: string;
+  /** @example "WB7DRDWrJZRGbYrv2CKGkqbzvqdC" */
+  user_id: string;
+}
+
 export interface EntitiesDiscord {
   /** @example "2022-06-05T14:26:02.302718+03:00" */
   created_at: string;
@@ -199,6 +217,8 @@ export interface EntitiesMessageThread {
   color: string;
   /** @example "+18005550100" */
   contact: string;
+  /** ContactDetails is resolved at read time and never persisted. */
+  contact_details?: EntitiesContact;
   /** @example "2022-06-05T14:26:09.527976+03:00" */
   created_at: string;
   /** @example "32343a19-da5e-4b1b-a767-3298a73703ca" */
@@ -332,6 +352,26 @@ export interface EntitiesWebhook {
   user_id: string;
 }
 
+export interface RequestsContactItem {
+  emails?: string[];
+  /** @example "Alice Smith" */
+  name: string;
+  phone_numbers: string[];
+  properties?: Record<string, string>;
+}
+
+export interface RequestsContactStoreRequest {
+  contacts: RequestsContactItem[];
+}
+
+export interface RequestsContactUpdateRequest {
+  emails?: string[];
+  /** @example "Alice Smith" */
+  name: string;
+  phone_numbers: string[];
+  properties?: Record<string, string>;
+}
+
 export interface RequestsDiscordStore {
   incoming_channel_id: string;
   name: string;
@@ -625,6 +665,22 @@ export interface ResponsesBulkMessagesResponse {
   status: string;
 }
 
+export interface ResponsesContactResponse {
+  data: EntitiesContact;
+  /** @example "Request handled successfully" */
+  message: string;
+  /** @example "success" */
+  status: string;
+}
+
+export interface ResponsesContactsResponse {
+  data: EntitiesContact[];
+  /** @example "Request handled successfully" */
+  message: string;
+  /** @example "success" */
+  status: string;
+}
+
 export interface ResponsesDiscordResponse {
   data: EntitiesDiscord;
   /** @example "Request handled successfully" */

From 7dcde655dbfee7f0bef98b9e9f3dbd1bb64c93de Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 23:24:14 +0300
Subject: [PATCH 16/24] feat(web): add contacts Pinia store

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/stores/contacts.ts | 181 +++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 web/app/stores/contacts.ts

diff --git a/web/app/stores/contacts.ts b/web/app/stores/contacts.ts
new file mode 100644
index 000000000..5d5c10d82
--- /dev/null
+++ b/web/app/stores/contacts.ts
@@ -0,0 +1,181 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { EntitiesContact } from '~~/shared/types/api'
+import { getApiErrorMessage } from '~/utils/api-error'
+
+export interface ContactInput {
+  name: string
+  emails: string[]
+  phone_numbers: string[]
+  properties?: Record<string, string>
+}
+
+export const useContactsStore = defineStore('contacts', () => {
+  const contacts = ref<EntitiesContact[]>([])
+  const loading = ref(false)
+  const search = ref('')
+  const { apiFetch } = useApi()
+  const notificationsStore = useNotificationsStore()
+
+  const total = computed(() => contacts.value.length)
+
+  const filteredContacts = computed<EntitiesContact[]>(() => {
+    const term = search.value.trim().toLowerCase()
+    if (!term) return contacts.value
+
+    return contacts.value.filter((contact) => {
+      const name = contact.name.toLowerCase()
+      const emails = contact.emails.join(' ').toLowerCase()
+      const phoneNumbers = contact.phone_numbers.join(' ').toLowerCase()
+
+      return (
+        name.includes(term) ||
+        emails.includes(term) ||
+        phoneNumbers.includes(term)
+      )
+    })
+  })
+
+  async function loadContacts(force = false): Promise<void> {
+    if (contacts.value.length > 0 && !force) return
+
+    loading.value = true
+    try {
+      const response = await apiFetch<{ data: EntitiesContact[] }>(
+        '/v1/contacts',
+        {
+          params: { limit: 100 },
+        },
+      )
+      contacts.value = response.data ?? []
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while loading contacts'),
+        type: 'error',
+      })
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function saveContacts(
+    items: ContactInput | ContactInput[],
+  ): Promise<void> {
+    const contactsToSave = Array.isArray(items) ? items : [items]
+
+    loading.value = true
+    try {
+      await apiFetch('/v1/contacts', {
+        method: 'POST',
+        body: contactsToSave,
+      })
+      notificationsStore.addNotification({
+        message:
+          contactsToSave.length > 1 ? 'Contacts created' : 'Contact created',
+        type: 'success',
+      })
+      await loadContacts(true)
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while saving contacts'),
+        type: 'error',
+      })
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function updateContact(
+    id: string,
+    payload: ContactInput,
+  ): Promise<void> {
+    loading.value = true
+    try {
+      await apiFetch(`/v1/contacts/${id}`, {
+        method: 'PUT',
+        body: payload,
+      })
+      notificationsStore.addNotification({
+        message: 'Contact updated',
+        type: 'success',
+      })
+      await loadContacts(true)
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while updating contact'),
+        type: 'error',
+      })
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function deleteContact(id: string): Promise<void> {
+    loading.value = true
+    try {
+      await apiFetch(`/v1/contacts/${id}`, { method: 'DELETE' })
+      contacts.value = contacts.value.filter((contact) => contact.id !== id)
+      notificationsStore.addNotification({
+        message: 'Contact deleted',
+        type: 'success',
+      })
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while deleting contact'),
+        type: 'error',
+      })
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function uploadCsv(file: File): Promise<void> {
+    loading.value = true
+    try {
+      const formData = new FormData()
+      formData.append('document', file)
+
+      await apiFetch('/v1/contacts/upload', {
+        method: 'POST',
+        body: formData,
+      })
+      notificationsStore.addNotification({
+        message: 'Contacts imported successfully',
+        type: 'success',
+      })
+      await loadContacts(true)
+    } catch (error: unknown) {
+      notificationsStore.addNotification({
+        message: getApiErrorMessage(error, 'Error while importing contacts'),
+        type: 'error',
+      })
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function resetState() {
+    contacts.value = []
+    loading.value = false
+    search.value = ''
+  }
+
+  return {
+    contacts,
+    loading,
+    search,
+    total,
+    filteredContacts,
+    loadContacts,
+    saveContacts,
+    updateContact,
+    deleteContact,
+    uploadCsv,
+    resetState,
+  }
+})

From 9f9592f5726d5f414b06689892fa14c3af7dab38 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 23:31:02 +0300
Subject: [PATCH 17/24] fix(web): avoid false contact reload errors

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/stores/contacts.ts | 73 +++++++++++++++++++++-----------------
 1 file changed, 41 insertions(+), 32 deletions(-)

diff --git a/web/app/stores/contacts.ts b/web/app/stores/contacts.ts
index 5d5c10d82..8e06a7011 100644
--- a/web/app/stores/contacts.ts
+++ b/web/app/stores/contacts.ts
@@ -66,22 +66,25 @@ export const useContactsStore = defineStore('contacts', () => {
 
     loading.value = true
     try {
-      await apiFetch('/v1/contacts', {
-        method: 'POST',
-        body: contactsToSave,
-      })
+      try {
+        await apiFetch('/v1/contacts', {
+          method: 'POST',
+          body: contactsToSave,
+        })
+      } catch (error: unknown) {
+        notificationsStore.addNotification({
+          message: getApiErrorMessage(error, 'Error while saving contacts'),
+          type: 'error',
+        })
+        throw error
+      }
+
       notificationsStore.addNotification({
         message:
           contactsToSave.length > 1 ? 'Contacts created' : 'Contact created',
         type: 'success',
       })
       await loadContacts(true)
-    } catch (error: unknown) {
-      notificationsStore.addNotification({
-        message: getApiErrorMessage(error, 'Error while saving contacts'),
-        type: 'error',
-      })
-      throw error
     } finally {
       loading.value = false
     }
@@ -93,21 +96,24 @@ export const useContactsStore = defineStore('contacts', () => {
   ): Promise<void> {
     loading.value = true
     try {
-      await apiFetch(`/v1/contacts/${id}`, {
-        method: 'PUT',
-        body: payload,
-      })
+      try {
+        await apiFetch(`/v1/contacts/${id}`, {
+          method: 'PUT',
+          body: payload,
+        })
+      } catch (error: unknown) {
+        notificationsStore.addNotification({
+          message: getApiErrorMessage(error, 'Error while updating contact'),
+          type: 'error',
+        })
+        throw error
+      }
+
       notificationsStore.addNotification({
         message: 'Contact updated',
         type: 'success',
       })
       await loadContacts(true)
-    } catch (error: unknown) {
-      notificationsStore.addNotification({
-        message: getApiErrorMessage(error, 'Error while updating contact'),
-        type: 'error',
-      })
-      throw error
     } finally {
       loading.value = false
     }
@@ -136,24 +142,27 @@ export const useContactsStore = defineStore('contacts', () => {
   async function uploadCsv(file: File): Promise<void> {
     loading.value = true
     try {
-      const formData = new FormData()
-      formData.append('document', file)
+      try {
+        const formData = new FormData()
+        formData.append('document', file)
+
+        await apiFetch('/v1/contacts/upload', {
+          method: 'POST',
+          body: formData,
+        })
+      } catch (error: unknown) {
+        notificationsStore.addNotification({
+          message: getApiErrorMessage(error, 'Error while importing contacts'),
+          type: 'error',
+        })
+        throw error
+      }
 
-      await apiFetch('/v1/contacts/upload', {
-        method: 'POST',
-        body: formData,
-      })
       notificationsStore.addNotification({
         message: 'Contacts imported successfully',
         type: 'success',
       })
       await loadContacts(true)
-    } catch (error: unknown) {
-      notificationsStore.addNotification({
-        message: getApiErrorMessage(error, 'Error while importing contacts'),
-        type: 'error',
-      })
-      throw error
     } finally {
       loading.value = false
     }

From d9f7807fa3f29f0be5d93bcaac4d0c2dfa438662 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sun, 19 Jul 2026 23:52:49 +0300
Subject: [PATCH 18/24] feat(web): add contacts management page with
 add/edit/delete/import dialogs

Add the /contacts page grounded in the existing Vuetify theme.

Header uses text-display-large; debounced search drives the API ?query= param.

VDataTable columns: Name, Phone Numbers, Emails, Created, Updated, Actions.

Rows show avatar initials, phone chips and relative timestamps via humanizeTime.

Add/edit/delete/import-CSV dialogs use opacity 0.9 and warning-colored Close controls.

Add/Edit has repeatable phone numbers, emails and free-form properties, preserved on edit.

CSV import surfaces row-indexed API validation errors inline, not only via a toast.

loadContacts forwards the trimmed search value as the query param, keeping Task 11's contract.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/pages/contacts/index.vue | 819 +++++++++++++++++++++++++++++++
 web/app/stores/contacts.ts       |   9 +-
 2 files changed, 825 insertions(+), 3 deletions(-)
 create mode 100644 web/app/pages/contacts/index.vue

diff --git a/web/app/pages/contacts/index.vue b/web/app/pages/contacts/index.vue
new file mode 100644
index 000000000..fdbad8a7a
--- /dev/null
+++ b/web/app/pages/contacts/index.vue
@@ -0,0 +1,819 @@
+<script setup lang="ts">
+import {
+  mdiAccount,
+  mdiAccountGroupOutline,
+  mdiAccountPlus,
+  mdiAlertCircleOutline,
+  mdiArrowLeft,
+  mdiClose,
+  mdiDelete,
+  mdiEmailOutline,
+  mdiFileUpload,
+  mdiMagnify,
+  mdiPencil,
+  mdiPhone,
+  mdiPlus,
+} from '@mdi/js'
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import type { EntitiesContact } from '~~/shared/types/api'
+import { useContactsStore, type ContactInput } from '~/stores/contacts'
+import { useFilters } from '~/composables/useFilters'
+import { ErrorMessages } from '~/utils/errors'
+import { toApiError } from '~/utils/api-error'
+
+definePageMeta({
+  middleware: ['auth'],
+})
+
+useHead({
+  title: 'Contacts - httpSMS',
+})
+
+interface PropertyRow {
+  key: string
+  value: string
+}
+
+interface ContactForm {
+  name: string
+  phoneNumbers: string[]
+  emails: string[]
+  properties: PropertyRow[]
+}
+
+const contactsStore = useContactsStore()
+const { formatPhoneNumber, humanizeTime, formatTimestamp } = useFilters()
+
+// Avatar backgrounds are picked deterministically from the Vuetify theme
+// palette so the table reads like an address book without inventing colors.
+const avatarPalette = ['primary', 'secondary', 'info', 'success']
+
+const headers = [
+  { title: 'Name', key: 'name', sortable: true },
+  { title: 'Phone Numbers', key: 'phone_numbers', sortable: false },
+  { title: 'Emails', key: 'emails', sortable: false },
+  { title: 'Created', key: 'created_at', sortable: true },
+  { title: 'Updated', key: 'updated_at', sortable: true },
+  { title: 'Actions', key: 'actions', sortable: false, align: 'end' as const },
+]
+
+const itemsPerPageOptions = [
+  { value: 10, title: '10' },
+  { value: 25, title: '25' },
+  { value: 50, title: '50' },
+  { value: 100, title: '100' },
+]
+
+const editDialog = ref(false)
+const deleteDialog = ref(false)
+const importDialog = ref(false)
+const saving = ref(false)
+
+const editingId = ref<string | null>(null)
+const pendingDelete = ref<EntitiesContact | null>(null)
+
+const form = ref<ContactForm>({
+  name: '',
+  phoneNumbers: [''],
+  emails: [''],
+  properties: [],
+})
+const formErrors = ref(new ErrorMessages())
+
+const importFile = ref<File | null>(null)
+const importErrors = ref<string[]>([])
+
+let searchTimer: ReturnType<typeof setTimeout> | undefined
+
+const searchTerm = computed({
+  get: () => contactsStore.search,
+  set: (value: string | null) => {
+    contactsStore.search = value ?? ''
+  },
+})
+
+const dialogTitle = computed(() =>
+  editingId.value ? 'Edit Contact' : 'Add Contact',
+)
+
+function emptyForm(): ContactForm {
+  return {
+    name: '',
+    phoneNumbers: [''],
+    emails: [''],
+    properties: [],
+  }
+}
+
+function initials(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) {
+    return ''
+  }
+  const first = parts[0] ?? ''
+  const last = parts.length > 1 ? (parts[parts.length - 1] ?? '') : ''
+  return (first.charAt(0) + last.charAt(0)).toUpperCase()
+}
+
+function avatarColor(name: string): string {
+  const key = name.trim()
+  if (!key) {
+    return 'primary'
+  }
+  let hash = 0
+  for (let index = 0; index < key.length; index += 1) {
+    hash = (hash + key.charCodeAt(index)) % avatarPalette.length
+  }
+  return avatarPalette[hash] ?? 'primary'
+}
+
+function relativeTime(value: string): string {
+  const humanized = humanizeTime(value)
+  return humanized ? `${humanized} ago` : 'just now'
+}
+
+function openAdd() {
+  editingId.value = null
+  form.value = emptyForm()
+  formErrors.value = new ErrorMessages()
+  editDialog.value = true
+}
+
+function openEdit(contact: EntitiesContact) {
+  editingId.value = contact.id
+  form.value = {
+    name: contact.name ?? '',
+    phoneNumbers:
+      contact.phone_numbers.length > 0 ? [...contact.phone_numbers] : [''],
+    emails: contact.emails.length > 0 ? [...contact.emails] : [''],
+    properties: Object.entries(contact.properties ?? {}).map(
+      ([key, value]) => ({ key, value }),
+    ),
+  }
+  formErrors.value = new ErrorMessages()
+  editDialog.value = true
+}
+
+function openDelete(contact: EntitiesContact) {
+  pendingDelete.value = contact
+  deleteDialog.value = true
+}
+
+function openImport() {
+  importFile.value = null
+  importErrors.value = []
+  importDialog.value = true
+}
+
+function addPhoneNumber() {
+  form.value.phoneNumbers.push('')
+}
+
+function removePhoneNumber(index: number) {
+  form.value.phoneNumbers.splice(index, 1)
+  if (form.value.phoneNumbers.length === 0) {
+    form.value.phoneNumbers.push('')
+  }
+}
+
+function addEmail() {
+  form.value.emails.push('')
+}
+
+function removeEmail(index: number) {
+  form.value.emails.splice(index, 1)
+  if (form.value.emails.length === 0) {
+    form.value.emails.push('')
+  }
+}
+
+function addProperty() {
+  form.value.properties.push({ key: '', value: '' })
+}
+
+function removeProperty(index: number) {
+  form.value.properties.splice(index, 1)
+}
+
+function buildPayload(): ContactInput {
+  const properties: Record<string, string> = {}
+  form.value.properties.forEach((row) => {
+    const key = row.key.trim()
+    if (key) {
+      properties[key] = row.value
+    }
+  })
+  return {
+    name: form.value.name.trim(),
+    phone_numbers: form.value.phoneNumbers
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0),
+    emails: form.value.emails
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0),
+    properties,
+  }
+}
+
+function validateForm(): boolean {
+  const bag = new ErrorMessages()
+  if (form.value.name.trim() === '') {
+    bag.add('name', 'The name is required.')
+  }
+  const hasPhone = form.value.phoneNumbers.some(
+    (value) => value.trim().length > 0,
+  )
+  if (!hasPhone) {
+    bag.add('phone_numbers', 'At least one phone number is required.')
+  }
+  formErrors.value = bag
+  return bag.size() === 0
+}
+
+function fieldErrorsFromApi(error: unknown): string[] {
+  const data = toApiError(error).data?.data
+  if (!data || typeof data !== 'object') {
+    return []
+  }
+  return Object.values(data).flat()
+}
+
+async function submitForm() {
+  if (!validateForm()) {
+    return
+  }
+  const payload = buildPayload()
+  saving.value = true
+  try {
+    if (editingId.value) {
+      await contactsStore.updateContact(editingId.value, payload)
+    } else {
+      await contactsStore.saveContacts([payload])
+    }
+    editDialog.value = false
+  } catch (error: unknown) {
+    // The store already surfaced a toast; retain the API field messages so the
+    // user can correct them inline instead of only seeing a transient toast.
+    const bag = new ErrorMessages()
+    const messages = fieldErrorsFromApi(error)
+    if (messages.length > 0) {
+      bag.addMany('contacts', messages)
+    }
+    formErrors.value = bag
+  } finally {
+    saving.value = false
+  }
+}
+
+async function confirmDelete() {
+  if (!pendingDelete.value?.id) {
+    return
+  }
+  saving.value = true
+  try {
+    await contactsStore.deleteContact(pendingDelete.value.id)
+    deleteDialog.value = false
+    pendingDelete.value = null
+  } catch {
+    // The store already surfaced the failure via a notification.
+  } finally {
+    saving.value = false
+  }
+}
+
+async function submitImport() {
+  if (!importFile.value) {
+    return
+  }
+  importErrors.value = []
+  saving.value = true
+  try {
+    await contactsStore.uploadCsv(importFile.value)
+    importDialog.value = false
+    importFile.value = null
+  } catch (error: unknown) {
+    // The store already surfaced a toast; keep the row-indexed messages inline
+    // so the user can see exactly which CSV rows failed validation.
+    importErrors.value = fieldErrorsFromApi(error)
+  } finally {
+    saving.value = false
+  }
+}
+
+watch(
+  () => contactsStore.search,
+  () => {
+    if (searchTimer) {
+      clearTimeout(searchTimer)
+    }
+    searchTimer = setTimeout(() => {
+      contactsStore.loadContacts(true).catch(() => {
+        // The store already surfaced the failure via a notification.
+      })
+    }, 350)
+  },
+)
+
+onMounted(() => {
+  contactsStore.loadContacts(true).catch(() => {
+    // The store already surfaced the failure via a notification.
+  })
+})
+
+onBeforeUnmount(() => {
+  if (searchTimer) {
+    clearTimeout(searchTimer)
+  }
+})
+</script>
+
+<template>
+  <VContainer fluid class="px-0 pt-0">
+    <VAppBar>
+      <VBtn icon to="/threads" aria-label="Back to messages">
+        <VIcon :icon="mdiArrowLeft" />
+      </VBtn>
+      <VToolbarTitle>Contacts</VToolbarTitle>
+      <VProgressLinear
+        :active="contactsStore.loading"
+        :indeterminate="contactsStore.loading"
+        color="primary"
+        location="bottom"
+        absolute
+      />
+    </VAppBar>
+
+    <VContainer class="pt-0">
+      <VRow>
+        <VCol cols="12" md="10" offset-md="1" xxl="8" offset-xxl="2">
+          <div class="d-flex flex-column flex-md-row align-md-center mb-6 mt-3">
+            <div>
+              <h1 class="text-display-large mb-1">Contacts</h1>
+              <p class="text-medium-emphasis mb-0">
+                Manage your contacts. {{ contactsStore.total }} total
+              </p>
+            </div>
+            <VSpacer />
+            <div class="d-flex flex-column flex-sm-row ga-3 mt-4 mt-md-0">
+              <VBtn
+                variant="outlined"
+                color="primary"
+                :prepend-icon="mdiFileUpload"
+                @click="openImport"
+              >
+                Import CSV
+              </VBtn>
+              <VBtn
+                color="primary"
+                variant="flat"
+                :prepend-icon="mdiAccountPlus"
+                @click="openAdd"
+              >
+                Add Contact
+              </VBtn>
+            </div>
+          </div>
+
+          <VTextField
+            v-model="searchTerm"
+            :prepend-inner-icon="mdiMagnify"
+            label="Search by name, phone number or email"
+            variant="outlined"
+            density="comfortable"
+            clearable
+            hide-details
+            class="mb-4"
+          />
+
+          <VCard variant="outlined">
+            <VDataTable
+              :headers="headers"
+              :items="contactsStore.contacts"
+              :loading="contactsStore.loading"
+              :items-per-page="10"
+              :items-per-page-options="itemsPerPageOptions"
+              item-value="id"
+              hover
+              loading-text="Loading contacts…"
+            >
+              <template #[`item.name`]="{ item }">
+                <div class="d-flex align-center py-2">
+                  <VAvatar
+                    :color="avatarColor(item.name)"
+                    size="40"
+                    class="mr-3"
+                  >
+                    <span
+                      v-if="initials(item.name)"
+                      class="text-body-1 font-weight-medium"
+                      >{{ initials(item.name) }}</span
+                    >
+                    <VIcon v-else :icon="mdiAccount" />
+                  </VAvatar>
+                  <span class="font-weight-medium">{{ item.name }}</span>
+                </div>
+              </template>
+
+              <template #[`item.phone_numbers`]="{ item }">
+                <div
+                  v-if="item.phone_numbers.length"
+                  class="d-flex flex-column ga-1 py-2"
+                >
+                  <VChip
+                    v-for="phone in item.phone_numbers"
+                    :key="phone"
+                    size="small"
+                    variant="tonal"
+                    color="primary"
+                    :prepend-icon="mdiPhone"
+                  >
+                    {{ formatPhoneNumber(phone) }}
+                  </VChip>
+                </div>
+                <span v-else class="text-medium-emphasis">—</span>
+              </template>
+
+              <template #[`item.emails`]="{ item }">
+                <div
+                  v-if="item.emails.length"
+                  class="d-flex flex-column ga-1 py-2"
+                >
+                  <span
+                    v-for="email in item.emails"
+                    :key="email"
+                    class="d-flex align-center text-body-2"
+                  >
+                    <VIcon
+                      :icon="mdiEmailOutline"
+                      size="x-small"
+                      class="mr-1 text-medium-emphasis"
+                    />
+                    {{ email }}
+                  </span>
+                </div>
+                <span v-else class="text-medium-emphasis">—</span>
+              </template>
+
+              <template #[`item.created_at`]="{ item }">
+                <span :title="formatTimestamp(item.created_at)">{{
+                  relativeTime(item.created_at)
+                }}</span>
+              </template>
+
+              <template #[`item.updated_at`]="{ item }">
+                <span :title="formatTimestamp(item.updated_at)">{{
+                  relativeTime(item.updated_at)
+                }}</span>
+              </template>
+
+              <template #[`item.actions`]="{ item }">
+                <div class="d-flex justify-end">
+                  <VBtn
+                    :icon="mdiPencil"
+                    variant="text"
+                    size="small"
+                    aria-label="Edit contact"
+                    @click="openEdit(item)"
+                  />
+                  <VBtn
+                    :icon="mdiDelete"
+                    variant="text"
+                    size="small"
+                    color="error"
+                    aria-label="Delete contact"
+                    @click="openDelete(item)"
+                  />
+                </div>
+              </template>
+
+              <template #no-data>
+                <div class="text-center py-12">
+                  <VIcon
+                    :icon="mdiAccountGroupOutline"
+                    size="64"
+                    class="text-medium-emphasis mb-3"
+                  />
+                  <p class="text-title-medium mb-1">
+                    {{
+                      searchTerm
+                        ? 'No contacts match your search'
+                        : 'No contacts yet'
+                    }}
+                  </p>
+                  <p class="text-medium-emphasis mb-4">
+                    {{
+                      searchTerm
+                        ? 'Try a different name, phone number or email.'
+                        : 'Add your first contact or import them from a CSV file.'
+                    }}
+                  </p>
+                  <VBtn
+                    v-if="!searchTerm"
+                    color="primary"
+                    variant="flat"
+                    :prepend-icon="mdiAccountPlus"
+                    @click="openAdd"
+                  >
+                    Add Contact
+                  </VBtn>
+                </div>
+              </template>
+            </VDataTable>
+          </VCard>
+        </VCol>
+      </VRow>
+    </VContainer>
+
+    <!-- Add / Edit contact dialog -->
+    <VDialog v-model="editDialog" max-width="640" opacity="0.9">
+      <VCard>
+        <VCardTitle class="d-flex align-center">
+          <span>{{ dialogTitle }}</span>
+          <VSpacer />
+          <VBtn
+            :icon="mdiClose"
+            variant="text"
+            color="warning"
+            size="small"
+            aria-label="Close dialog"
+            @click="editDialog = false"
+          />
+        </VCardTitle>
+        <VCardText>
+          <VAlert
+            v-if="formErrors.get('contacts').length"
+            type="error"
+            variant="tonal"
+            density="comfortable"
+            class="mb-4"
+            :icon="mdiAlertCircleOutline"
+          >
+            <ul class="pl-4 mb-0">
+              <li v-for="message in formErrors.get('contacts')" :key="message">
+                {{ message }}
+              </li>
+            </ul>
+          </VAlert>
+
+          <VTextField
+            v-model="form.name"
+            label="Name"
+            variant="outlined"
+            density="comfortable"
+            :prepend-inner-icon="mdiAccount"
+            :error="formErrors.has('name')"
+            :error-messages="formErrors.get('name')"
+            class="mb-2"
+          />
+
+          <div class="d-flex align-center mt-2 mb-1">
+            <span class="text-subtitle-2">Phone Numbers</span>
+            <VSpacer />
+            <VBtn
+              variant="text"
+              color="primary"
+              size="small"
+              :prepend-icon="mdiPlus"
+              @click="addPhoneNumber"
+            >
+              Add
+            </VBtn>
+          </div>
+          <div
+            v-for="(phone, index) in form.phoneNumbers"
+            :key="`phone-${index}`"
+            class="d-flex align-start ga-2"
+          >
+            <VTextField
+              v-model="form.phoneNumbers[index]"
+              :label="`Phone number ${index + 1}`"
+              placeholder="+18005550199"
+              variant="outlined"
+              density="comfortable"
+              :prepend-inner-icon="mdiPhone"
+              :error="index === 0 && formErrors.has('phone_numbers')"
+              :error-messages="
+                index === 0 ? formErrors.get('phone_numbers') : []
+              "
+            />
+            <VBtn
+              :icon="mdiClose"
+              variant="text"
+              size="small"
+              class="mt-1"
+              aria-label="Remove phone number"
+              @click="removePhoneNumber(index)"
+            />
+          </div>
+
+          <div class="d-flex align-center mt-2 mb-1">
+            <span class="text-subtitle-2">Email Addresses</span>
+            <VSpacer />
+            <VBtn
+              variant="text"
+              color="primary"
+              size="small"
+              :prepend-icon="mdiPlus"
+              @click="addEmail"
+            >
+              Add
+            </VBtn>
+          </div>
+          <div
+            v-for="(email, index) in form.emails"
+            :key="`email-${index}`"
+            class="d-flex align-start ga-2"
+          >
+            <VTextField
+              v-model="form.emails[index]"
+              :label="`Email ${index + 1}`"
+              placeholder="alice@example.com"
+              variant="outlined"
+              density="comfortable"
+              :prepend-inner-icon="mdiEmailOutline"
+            />
+            <VBtn
+              :icon="mdiClose"
+              variant="text"
+              size="small"
+              class="mt-1"
+              aria-label="Remove email"
+              @click="removeEmail(index)"
+            />
+          </div>
+
+          <div class="d-flex align-center mt-2 mb-1">
+            <span class="text-subtitle-2">Properties</span>
+            <VSpacer />
+            <VBtn
+              variant="text"
+              color="primary"
+              size="small"
+              :prepend-icon="mdiPlus"
+              @click="addProperty"
+            >
+              Add
+            </VBtn>
+          </div>
+          <p
+            v-if="!form.properties.length"
+            class="text-medium-emphasis text-body-2 mb-2"
+          >
+            Add custom key/value details such as company or address.
+          </p>
+          <div
+            v-for="(property, index) in form.properties"
+            :key="`property-${index}`"
+            class="d-flex align-start ga-2"
+          >
+            <VTextField
+              v-model="property.key"
+              label="Key"
+              variant="outlined"
+              density="comfortable"
+            />
+            <VTextField
+              v-model="property.value"
+              label="Value"
+              variant="outlined"
+              density="comfortable"
+            />
+            <VBtn
+              :icon="mdiClose"
+              variant="text"
+              size="small"
+              class="mt-1"
+              aria-label="Remove property"
+              @click="removeProperty(index)"
+            />
+          </div>
+        </VCardText>
+        <VCardActions>
+          <VSpacer />
+          <VBtn color="warning" variant="text" @click="editDialog = false">
+            Close
+          </VBtn>
+          <VBtn
+            color="primary"
+            variant="flat"
+            :loading="saving"
+            :disabled="saving"
+            @click="submitForm"
+          >
+            Save
+          </VBtn>
+        </VCardActions>
+      </VCard>
+    </VDialog>
+
+    <!-- Delete contact dialog -->
+    <VDialog v-model="deleteDialog" max-width="480" opacity="0.9">
+      <VCard>
+        <VCardTitle class="d-flex align-center">
+          <span>Delete Contact</span>
+          <VSpacer />
+          <VBtn
+            :icon="mdiClose"
+            variant="text"
+            color="warning"
+            size="small"
+            aria-label="Close dialog"
+            @click="deleteDialog = false"
+          />
+        </VCardTitle>
+        <VCardText>
+          Are you sure you want to delete
+          <strong>{{ pendingDelete?.name }}</strong
+          >? This action cannot be undone.
+        </VCardText>
+        <VCardActions>
+          <VSpacer />
+          <VBtn color="warning" variant="text" @click="deleteDialog = false">
+            Close
+          </VBtn>
+          <VBtn
+            color="error"
+            variant="flat"
+            :prepend-icon="mdiDelete"
+            :loading="saving"
+            :disabled="saving"
+            @click="confirmDelete"
+          >
+            Delete
+          </VBtn>
+        </VCardActions>
+      </VCard>
+    </VDialog>
+
+    <!-- Import CSV dialog -->
+    <VDialog v-model="importDialog" max-width="600" opacity="0.9">
+      <VCard>
+        <VCardTitle class="d-flex align-center">
+          <span>Import Contacts from CSV</span>
+          <VSpacer />
+          <VBtn
+            :icon="mdiClose"
+            variant="text"
+            color="warning"
+            size="small"
+            aria-label="Close dialog"
+            @click="importDialog = false"
+          />
+        </VCardTitle>
+        <VCardText>
+          <p class="mb-4">
+            Download the
+            <a
+              class="text-decoration-none hover:text-decoration-underline"
+              href="/templates/httpsms-contacts.csv"
+              download
+              >CSV template</a
+            >, fill it in and upload it here. Separate multiple emails or phone
+            numbers within a cell using a semicolon (<code>;</code>).
+          </p>
+          <VFileInput
+            v-model="importFile"
+            label="CSV file"
+            color="primary"
+            accept=".csv,text/csv"
+            variant="outlined"
+            density="comfortable"
+            :prepend-icon="mdiFileUpload"
+            hide-details="auto"
+          />
+          <VAlert
+            v-if="importErrors.length"
+            type="error"
+            variant="tonal"
+            density="comfortable"
+            class="mt-4"
+            :icon="mdiAlertCircleOutline"
+          >
+            <p class="font-weight-medium mb-1">We couldn't import your file:</p>
+            <ul class="pl-4 mb-0">
+              <li v-for="message in importErrors" :key="message">
+                {{ message }}
+              </li>
+            </ul>
+          </VAlert>
+        </VCardText>
+        <VCardActions>
+          <VSpacer />
+          <VBtn color="warning" variant="text" @click="importDialog = false">
+            Close
+          </VBtn>
+          <VBtn
+            color="primary"
+            variant="flat"
+            :prepend-icon="mdiFileUpload"
+            :loading="saving"
+            :disabled="saving || !importFile"
+            @click="submitImport"
+          >
+            Import
+          </VBtn>
+        </VCardActions>
+      </VCard>
+    </VDialog>
+  </VContainer>
+</template>
diff --git a/web/app/stores/contacts.ts b/web/app/stores/contacts.ts
index 8e06a7011..eae10b448 100644
--- a/web/app/stores/contacts.ts
+++ b/web/app/stores/contacts.ts
@@ -41,11 +41,14 @@ export const useContactsStore = defineStore('contacts', () => {
 
     loading.value = true
     try {
+      const term = search.value.trim()
+      const params: Record<string, string | number> = { limit: 100 }
+      if (term) {
+        params.query = term
+      }
       const response = await apiFetch<{ data: EntitiesContact[] }>(
         '/v1/contacts',
-        {
-          params: { limit: 100 },
-        },
+        { params },
       )
       contacts.value = response.data ?? []
     } catch (error: unknown) {

From f18c57d3a5fad4f7118c026849fadfbcaa16c47b Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Mon, 20 Jul 2026 00:05:07 +0300
Subject: [PATCH 19/24] fix(web): guard stale contacts loads

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/stores/contacts.ts | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/web/app/stores/contacts.ts b/web/app/stores/contacts.ts
index eae10b448..9bf3e3b74 100644
--- a/web/app/stores/contacts.ts
+++ b/web/app/stores/contacts.ts
@@ -16,6 +16,7 @@ export const useContactsStore = defineStore('contacts', () => {
   const search = ref('')
   const { apiFetch } = useApi()
   const notificationsStore = useNotificationsStore()
+  let loadContactsGeneration = 0
 
   const total = computed(() => contacts.value.length)
 
@@ -39,6 +40,7 @@ export const useContactsStore = defineStore('contacts', () => {
   async function loadContacts(force = false): Promise<void> {
     if (contacts.value.length > 0 && !force) return
 
+    const generation = ++loadContactsGeneration
     loading.value = true
     try {
       const term = search.value.trim()
@@ -50,15 +52,22 @@ export const useContactsStore = defineStore('contacts', () => {
         '/v1/contacts',
         { params },
       )
-      contacts.value = response.data ?? []
+      if (generation === loadContactsGeneration) {
+        contacts.value = response.data ?? []
+      }
     } catch (error: unknown) {
+      if (generation !== loadContactsGeneration) {
+        return
+      }
       notificationsStore.addNotification({
         message: getApiErrorMessage(error, 'Error while loading contacts'),
         type: 'error',
       })
       throw error
     } finally {
-      loading.value = false
+      if (generation === loadContactsGeneration) {
+        loading.value = false
+      }
     }
   }
 
@@ -172,6 +181,7 @@ export const useContactsStore = defineStore('contacts', () => {
   }
 
   function resetState() {
+    loadContactsGeneration++
     contacts.value = []
     loading.value = false
     search.value = ''

From 6c8561a942c60af151079276e9e42e982313d78f Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Mon, 20 Jul 2026 00:11:40 +0300
Subject: [PATCH 20/24] feat(web): display contact names on threads

Preserve contact details across mark-read updates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/components/MessageThread.vue       | 24 ++++++++++++++++++----
 web/app/components/MessageThreadHeader.vue |  7 ++++++-
 web/app/composables/useFilters.ts          |  2 ++
 web/app/pages/threads/[id]/index.vue       | 13 +++++++++---
 web/app/stores/threads.ts                  | 15 +++++++++++++-
 5 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/web/app/components/MessageThread.vue b/web/app/components/MessageThread.vue
index 2a9834317..d62eeb098 100644
--- a/web/app/components/MessageThread.vue
+++ b/web/app/components/MessageThread.vue
@@ -7,12 +7,13 @@ import {
   mdiAlert,
   mdiAccount,
 } from '@mdi/js'
-import { formatPhoneNumber, startsWithLetter } from '~/utils/filters'
+import type { EntitiesMessageThread } from '~~/shared/types/api'
 
 const threadsStore = useThreadsStore()
 const phonesStore = usePhonesStore()
 const appStore = useAppStore()
 const notificationsStore = useNotificationsStore()
+const { formatPhoneNumber, startsWithLetter } = useFilters()
 
 function threadDate(date: string): string {
   return new Date(date).toLocaleString(undefined, {
@@ -27,6 +28,21 @@ function onInstallApp() {
     message: 'Downloading the httpSMS Android App',
   })
 }
+
+function threadContactName(thread: EntitiesMessageThread): string {
+  return thread.contact_details?.name?.trim() ?? ''
+}
+
+function threadContactTitle(thread: EntitiesMessageThread): string {
+  return threadContactName(thread) || formatPhoneNumber(thread.contact)
+}
+
+function threadAvatarInitial(thread: EntitiesMessageThread): string {
+  const contactName = threadContactName(thread)
+  if (contactName) return contactName.substring(0, 1)
+
+  return startsWithLetter(thread.contact) ? thread.contact.substring(0, 1) : ''
+}
 </script>
 
 <template>
@@ -104,16 +120,16 @@ function onInstallApp() {
             size="40"
             :badge="thread.is_read ? false : { color: 'primary', dotSize: 12 }"
           >
-            <v-icon v-if="!startsWithLetter(thread.contact)" color="white">{{
+            <v-icon v-if="!threadAvatarInitial(thread)" color="white">{{
               mdiAccount
             }}</v-icon>
             <span v-else class="text-white text-headline-small">{{
-              thread.contact.substring(0, 1)
+              threadAvatarInitial(thread)
             }}</span>
           </v-avatar>
         </template>
         <v-list-item-title :class="{ 'font-weight-bold': !thread.is_read }">{{
-          formatPhoneNumber(thread.contact)
+          threadContactTitle(thread)
         }}</v-list-item-title>
         <v-list-item-subtitle
           class="text-truncate mt-1"
diff --git a/web/app/components/MessageThreadHeader.vue b/web/app/components/MessageThreadHeader.vue
index 1e1a81eb2..12917b598 100644
--- a/web/app/components/MessageThreadHeader.vue
+++ b/web/app/components/MessageThreadHeader.vue
@@ -14,9 +14,9 @@ import {
   mdiDotsVertical,
   mdiMagnify,
   mdiCommentTextMultipleOutline,
+  mdiAccountMultiple,
   mdiCircle,
 } from '@mdi/js'
-import { formatPhoneNumber, phoneCountry, humanizeTime } from '~/utils/filters'
 import type { EntitiesPhone } from '~~/shared/types/api'
 
 const router = useRouter()
@@ -28,6 +28,7 @@ const threadsStore = useThreadsStore()
 const appStore = useAppStore()
 const notificationsStore = useNotificationsStore()
 const redirectPreferenceStore = useRedirectPreferenceStore()
+const { formatPhoneNumber, phoneCountry, humanizeTime } = useFilters()
 
 const selectedMenuItem = ref(-1)
 
@@ -180,6 +181,10 @@ async function logout() {
           <template #prepend><v-icon :icon="mdiMagnify" /></template>
           <v-list-item-title>Search Messages</v-list-item-title>
         </v-list-item>
+        <v-list-item :to="{ name: 'contacts' }">
+          <template #prepend><v-icon :icon="mdiAccountMultiple" /></template>
+          <v-list-item-title>Contacts</v-list-item-title>
+        </v-list-item>
         <v-list-item :to="{ name: 'settings' }">
           <template #prepend><v-icon :icon="mdiAccountCog" /></template>
           <v-list-item-title>Settings</v-list-item-title>
diff --git a/web/app/composables/useFilters.ts b/web/app/composables/useFilters.ts
index c84157ea5..cca405dc5 100644
--- a/web/app/composables/useFilters.ts
+++ b/web/app/composables/useFilters.ts
@@ -7,6 +7,7 @@ import {
   formatBillingPeriod,
   formatBillingPeriodDateOrdinal,
   humanizeTime,
+  startsWithLetter,
 } from '../utils/filters'
 import { capitalize } from '../utils/capitalize'
 
@@ -20,6 +21,7 @@ export function useFilters() {
     formatBillingPeriod,
     formatBillingPeriodDateOrdinal,
     humanizeTime,
+    startsWithLetter,
     capitalize,
   }
 }
diff --git a/web/app/pages/threads/[id]/index.vue b/web/app/pages/threads/[id]/index.vue
index 73632a64c..68882d461 100644
--- a/web/app/pages/threads/[id]/index.vue
+++ b/web/app/pages/threads/[id]/index.vue
@@ -19,7 +19,6 @@ import Pusher from 'pusher-js'
 import type { Channel } from 'pusher-js'
 import { isValidPhoneNumber } from 'libphonenumber-js'
 import type { EntitiesMessage } from '~~/shared/types/api'
-import { startsWithLetter } from '~/utils/filters'
 
 definePageMeta({
   middleware: ['auth'],
@@ -33,7 +32,7 @@ const route = useRoute()
 const router = useRouter()
 const config = useRuntimeConfig()
 const { lgAndUp, mdAndDown, mdAndUp } = useDisplay()
-const { formatPhoneNumber } = useFilters()
+const { formatPhoneNumber, startsWithLetter } = useFilters()
 const notificationsStore = useNotificationsStore()
 const authStore = useAuthStore()
 const phonesStore = usePhonesStore()
@@ -104,6 +103,14 @@ function formatAttachmentName(url: string): string {
   return url
 }
 
+function currentThreadContactTitle(): string {
+  const thread = threadsStore.currentThread
+  if (!thread) return ''
+  return (
+    thread.contact_details?.name?.trim() || formatPhoneNumber(thread.contact)
+  )
+}
+
 function scrollToElement() {
   const el = messageBody.value
   if (el) {
@@ -268,7 +275,7 @@ onBeforeUnmount(() => {
           <VIcon :icon="mdiArrowLeft" />
         </VBtn>
         <VToolbarTitle v-if="threadsStore.currentThread">
-          {{ formatPhoneNumber(threadsStore.currentThread.contact) }}
+          {{ currentThreadContactTitle() }}
         </VToolbarTitle>
         <VMenu>
           <template #activator="{ props }">
diff --git a/web/app/stores/threads.ts b/web/app/stores/threads.ts
index 7e3002624..fdc7094ea 100644
--- a/web/app/stores/threads.ts
+++ b/web/app/stores/threads.ts
@@ -28,7 +28,19 @@ export const useThreadsStore = defineStore('threads', () => {
     const index = threads.value.findIndex(
       (thread) => thread.id === updatedThread.id,
     )
-    if (index !== -1) threads.value[index] = updatedThread
+    if (index !== -1) {
+      const existingThread = threads.value[index]
+      threads.value[index] = {
+        ...updatedThread,
+        // Mark-read PUT responses are not contact-enriched; keep the resolved
+        // contact so display names do not disappear after the thread updates.
+        contact_details:
+          updatedThread.contact_details ??
+          (updatedThread.contact === existingThread.contact
+            ? existingThread.contact_details
+            : undefined),
+      }
+    }
   }
 
   async function loadThreads() {
@@ -45,6 +57,7 @@ export const useThreadsStore = defineStore('threads', () => {
           owner: phonesStore.owner ?? phonesStore.phones[0]?.phone_number,
           limit: 100,
           is_archived: archivedThreads.value,
+          contacts: true,
         },
       },
     )

From eff5632f6afb65c638884cbda4f39303c1783440 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Mon, 20 Jul 2026 00:51:32 +0300
Subject: [PATCH 21/24] 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>
---
 api/docs/docs.go                              | 10 ++-
 api/docs/swagger.json                         | 10 ++-
 api/docs/swagger.yaml                         |  9 +++
 api/pkg/entities/contact_test.go              |  2 -
 api/pkg/handlers/contact_handler.go           | 17 +++--
 api/pkg/handlers/contact_handler_test.go      | 62 +++++++++++++++++++
 api/pkg/handlers/handler.go                   |  9 +++
 api/pkg/repositories/contact_repository.go    |  4 ++
 .../repositories/gorm_contact_repository.go   | 41 +++++++++---
 .../gorm_contact_repository_test.go           | 39 ++++++++++++
 api/pkg/requests/contact_store.go             |  7 ++-
 api/pkg/responses/contact_responses.go        |  3 +
 api/pkg/services/contact_service.go           | 14 +++++
 api/pkg/services/contact_service_test.go      | 37 +++++++++++
 .../validators/contact_handler_validator.go   | 10 ++-
 .../contact_handler_validator_test.go         | 19 ++++++
 16 files changed, 269 insertions(+), 24 deletions(-)

diff --git a/api/docs/docs.go b/api/docs/docs.go
index ce6103547..1dfeea570 100644
--- a/api/docs/docs.go
+++ b/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
                 }
             }
         },
diff --git a/api/docs/swagger.json b/api/docs/swagger.json
index 1711970a2..0605e5a45 100644
--- a/api/docs/swagger.json
+++ b/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
                 }
             }
         },
diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yaml
index 5898c3762..b62a0687e 100644
--- a/api/docs/swagger.yaml
+++ b/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
diff --git a/api/pkg/entities/contact_test.go b/api/pkg/entities/contact_test.go
index 537adfbea..b20d99414 100644
--- a/api/pkg/entities/contact_test.go
+++ b/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")
 }
diff --git a/api/pkg/handlers/contact_handler.go b/api/pkg/handlers/contact_handler.go
index 94e627eb4..a7d4ff046 100644
--- a/api/pkg/handlers/contact_handler.go
+++ b/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))
diff --git a/api/pkg/handlers/contact_handler_test.go b/api/pkg/handlers/contact_handler_test.go
index 097ce1b2b..9cfabe069 100644
--- a/api/pkg/handlers/contact_handler_test.go
+++ b/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)
diff --git a/api/pkg/handlers/handler.go b/api/pkg/handlers/handler.go
index 070e2db71..1f655b447 100644
--- a/api/pkg/handlers/handler.go
+++ b/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",
diff --git a/api/pkg/repositories/contact_repository.go b/api/pkg/repositories/contact_repository.go
index a03df1948..09ca3204d 100644
--- a/api/pkg/repositories/contact_repository.go
+++ b/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)
 
diff --git a/api/pkg/repositories/gorm_contact_repository.go b/api/pkg/repositories/gorm_contact_repository.go
index cebb38678..a6ddbb912 100644
--- a/api/pkg/repositories/gorm_contact_repository.go
+++ b/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()
diff --git a/api/pkg/repositories/gorm_contact_repository_test.go b/api/pkg/repositories/gorm_contact_repository_test.go
index b30b7d086..5fd4251f4 100644
--- a/api/pkg/repositories/gorm_contact_repository_test.go
+++ b/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)
 
diff --git a/api/pkg/requests/contact_store.go b/api/pkg/requests/contact_store.go
index 52e310d7b..7ddf147b0 100644
--- a/api/pkg/requests/contact_store.go
+++ b/api/pkg/requests/contact_store.go
@@ -49,7 +49,7 @@ func (input *ContactStoreRequest) UnmarshalJSON(data []byte) error {
 // Sanitize trims and normalizes each contact item.
 func (input ContactStoreRequest) Sanitize() ContactStoreRequest {
 	for index := range input.Contacts {
-		input.Contacts[index] = sanitizeContactItem(input.Contacts[index])
+		input.Contacts[index] = SanitizeContactItem(input.Contacts[index])
 	}
 	return input
 }
@@ -78,7 +78,10 @@ func (input *ContactStoreRequest) ToContacts(userID entities.UserID) []*entities
 	return contacts
 }
 
-func sanitizeContactItem(item ContactItem) ContactItem {
+// SanitizeContactItem trims and normalizes a single contact item so the CSV
+// upload and JSON create paths accept and normalize identical values (e.g. a
+// phone number without a leading "+" or an email with mixed case/whitespace).
+func SanitizeContactItem(item ContactItem) ContactItem {
 	item.Name = strings.TrimSpace(item.Name)
 	item.Emails = sanitizeUniqueStrings(item.Emails, func(value string) string {
 		return strings.ToLower(strings.TrimSpace(value))
diff --git a/api/pkg/responses/contact_responses.go b/api/pkg/responses/contact_responses.go
index e8f2a319a..76f72cfcd 100644
--- a/api/pkg/responses/contact_responses.go
+++ b/api/pkg/responses/contact_responses.go
@@ -12,4 +12,7 @@ type ContactResponse struct {
 type ContactsResponse struct {
 	response
 	Data []entities.Contact `json:"data"`
+	// Total is the number of contacts matching the request filter for the
+	// user, independent of the pagination skip/limit applied to Data.
+	Total int64 `json:"total" example:"57"`
 }
diff --git a/api/pkg/services/contact_service.go b/api/pkg/services/contact_service.go
index 005e51f0a..d6b86e0d3 100644
--- a/api/pkg/services/contact_service.go
+++ b/api/pkg/services/contact_service.go
@@ -84,6 +84,20 @@ func (service *ContactService) Index(ctx context.Context, userID entities.UserID
 	return contacts, nil
 }
 
+// Count returns the total number of contacts for a user matching the same
+// search filter as Index, ignoring pagination. It lets callers report an
+// accurate total independent of the current page's skip/limit.
+func (service *ContactService) Count(ctx context.Context, userID entities.UserID, params repositories.IndexParams) (int64, error) {
+	ctx, span := service.tracer.Start(ctx)
+	defer span.End()
+
+	total, err := service.repository.Count(ctx, userID, params)
+	if err != nil {
+		return 0, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot count contacts for user [%s]", userID))
+	}
+	return total, nil
+}
+
 // Update persists changes to a contact and invalidates the cached map.
 func (service *ContactService) Update(ctx context.Context, contact *entities.Contact) error {
 	ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)
diff --git a/api/pkg/services/contact_service_test.go b/api/pkg/services/contact_service_test.go
index 596a7a5ec..5eb38eb72 100644
--- a/api/pkg/services/contact_service_test.go
+++ b/api/pkg/services/contact_service_test.go
@@ -90,6 +90,7 @@ type fakeContactRepo struct {
 	updateCalls []*entities.Contact
 	loadCalls   []loadCall
 	indexCalls  []indexCall
+	countCalls  []indexCall
 	deleteCalls []deleteCall
 	fetchAll    int
 
@@ -97,10 +98,12 @@ type fakeContactRepo struct {
 	updateErr error
 	loadErr   error
 	indexErr  error
+	countErr  error
 	deleteErr error
 	fetchErr  error
 
 	indexResult []entities.Contact
+	countResult int64
 }
 
 type loadCall struct {
@@ -169,6 +172,17 @@ func (r *fakeContactRepo) Index(_ context.Context, userID entities.UserID, param
 	return &out, nil
 }
 
+func (r *fakeContactRepo) Count(_ context.Context, userID entities.UserID, params repositories.IndexParams) (int64, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.countCalls = append(r.countCalls, indexCall{userID: userID, params: params})
+	if r.countErr != nil {
+		return 0, r.countErr
+	}
+	return r.countResult, nil
+}
+
 func (r *fakeContactRepo) FetchAll(_ context.Context, _ entities.UserID) (*[]entities.Contact, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
@@ -583,6 +597,29 @@ func TestContactService_Index_RepositoryErrorIsWrapped(t *testing.T) {
 	assert.Contains(t, err.Error(), "index boom")
 }
 
+func TestContactService_Count_DelegatesParamsAndReturnsTotal(t *testing.T) {
+	repo := &fakeContactRepo{countResult: 57}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	params := repositories.IndexParams{Skip: 5, Limit: 10, Query: "Ali"}
+	total, err := service.Count(context.Background(), entities.UserID("u1"), params)
+	require.NoError(t, err)
+	assert.Equal(t, int64(57), total)
+
+	require.Len(t, repo.countCalls, 1)
+	assert.Equal(t, entities.UserID("u1"), repo.countCalls[0].userID)
+	assert.Equal(t, params, repo.countCalls[0].params)
+}
+
+func TestContactService_Count_RepositoryErrorIsWrapped(t *testing.T) {
+	repo := &fakeContactRepo{countErr: errors.New("count boom")}
+	service := newContactServiceForTest(t, repo, newFakeCache(), nil)
+
+	_, err := service.Count(context.Background(), entities.UserID("u1"), repositories.IndexParams{})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "count boom")
+}
+
 func TestContactService_Update_RepositoryErrorIsWrappedAndSkipsInvalidation(t *testing.T) {
 	repo := &fakeContactRepo{updateErr: errors.New("update boom")}
 	appCache := newFakeCache()
diff --git a/api/pkg/validators/contact_handler_validator.go b/api/pkg/validators/contact_handler_validator.go
index 2ca5319b9..8d2bc4a85 100644
--- a/api/pkg/validators/contact_handler_validator.go
+++ b/api/pkg/validators/contact_handler_validator.go
@@ -146,11 +146,15 @@ func (validator *ContactHandlerValidator) ValidateUpload(ctx context.Context, us
 
 	items := make([]requests.ContactItem, 0, len(rows))
 	for _, row := range rows {
-		item := requests.ContactItem{
-			Name:         strings.TrimSpace(row.values[contactCSVColumnName]),
+		// Sanitize each row exactly like the JSON create path (SanitizeContactItem)
+		// before validating it, so both entry points accept and normalize the same
+		// phone/email formats. Row-indexed error messages are preserved because the
+		// row number is still passed to validateItem.
+		item := requests.SanitizeContactItem(requests.ContactItem{
+			Name:         row.values[contactCSVColumnName],
 			Emails:       splitContactMultiValue(row.values[contactCSVColumnEmails]),
 			PhoneNumbers: splitContactMultiValue(row.values[contactCSVColumnPhones]),
-		}
+		})
 		items = append(items, item)
 		validator.validateItem(result, contactUploadDocumentKey, "Row", row.number, item)
 	}
diff --git a/api/pkg/validators/contact_handler_validator_test.go b/api/pkg/validators/contact_handler_validator_test.go
index 84570881f..2216714f6 100644
--- a/api/pkg/validators/contact_handler_validator_test.go
+++ b/api/pkg/validators/contact_handler_validator_test.go
@@ -366,6 +366,25 @@ func TestContactValidator_ValidateUpload_ReturnsRowIndexedValidationErrors(t *te
 	assert.Contains(t, documentErrors, "not-a-number")
 }
 
+func TestContactValidator_ValidateUpload_SanitizesItemsLikeJSONBeforeValidation(t *testing.T) {
+	validator := newContactUploadValidator()
+	// The phone number lacks a leading "+" and the email has mixed case and
+	// surrounding whitespace. The JSON create path sanitizes these before
+	// validation, so the CSV path must accept and normalize them identically.
+	header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join([]string{
+		"Name,Emails,PhoneNumbers",
+		"Alice, Alice@Example.com ,18005550199",
+	}, "\n"))
+
+	items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)
+
+	require.Empty(t, errs, "sanitized CSV rows must pass validation like the JSON path")
+	require.Len(t, items, 1)
+	assert.Equal(t, "Alice", items[0].Name)
+	assert.Equal(t, []string{"+18005550199"}, items[0].PhoneNumbers)
+	assert.Equal(t, []string{"alice@example.com"}, items[0].Emails)
+}
+
 func multipartFileHeader(t *testing.T, filename string, contentType string, content string) *multipart.FileHeader {
 	t.Helper()
 

From b2dbc9390876a0715f7a2ce49d784e59988c5114 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Mon, 20 Jul 2026 00:51:49 +0300
Subject: [PATCH 22/24] feat(web): server-side pagination for the contacts page

- store total now reflects the server count; loadContacts accepts skip and
  limit and remembers the current window so mutation refreshes stay in place
- contacts page uses VDataTableServer with items-length bound to the server
  total; page/size changes fetch the correct skip/limit and a debounced
  query resets to page 1 without duplicate requests
- delete bumps the load generation so an in-flight load cannot resurrect a
  deleted contact, without leaving loading stuck or hiding delete errors
- remove the dead filteredContacts computed and add defensive null
  coalescing for emails/phone_numbers in the table display
- regenerate API models with the new contacts total field

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/pages/contacts/index.vue | 69 ++++++++++++++++++++++-------
 web/app/stores/contacts.ts       | 76 ++++++++++++++++++++++----------
 web/shared/types/api.ts          |  6 +++
 3 files changed, 111 insertions(+), 40 deletions(-)

diff --git a/web/app/pages/contacts/index.vue b/web/app/pages/contacts/index.vue
index fdbad8a7a..3d0ce297a 100644
--- a/web/app/pages/contacts/index.vue
+++ b/web/app/pages/contacts/index.vue
@@ -69,6 +69,13 @@ const deleteDialog = ref(false)
 const importDialog = ref(false)
 const saving = ref(false)
 
+// Server-driven pagination state for VDataTableServer.
+const page = ref(1)
+const itemsPerPage = ref(10)
+// initialLoadComplete gates the table's initial @update:options emit so the
+// first fetch is driven by onMounted rather than firing twice on mount.
+const initialLoadComplete = ref(false)
+
 const editingId = ref<string | null>(null)
 const pendingDelete = ref<EntitiesContact | null>(null)
 
@@ -143,9 +150,10 @@ function openEdit(contact: EntitiesContact) {
   editingId.value = contact.id
   form.value = {
     name: contact.name ?? '',
-    phoneNumbers:
-      contact.phone_numbers.length > 0 ? [...contact.phone_numbers] : [''],
-    emails: contact.emails.length > 0 ? [...contact.emails] : [''],
+    phoneNumbers: contact.phone_numbers?.length
+      ? [...contact.phone_numbers]
+      : [''],
+    emails: contact.emails?.length ? [...contact.emails] : [''],
     properties: Object.entries(contact.properties ?? {}).map(
       ([key, value]) => ({ key, value }),
     ),
@@ -300,6 +308,27 @@ async function submitImport() {
   }
 }
 
+function fetchContacts() {
+  const skip = (page.value - 1) * itemsPerPage.value
+  return contactsStore
+    .loadContacts({ force: true, skip, limit: itemsPerPage.value })
+    .catch(() => {
+      // The store already surfaced the failure via a notification.
+    })
+}
+
+function onUpdateOptions(options: { page: number; itemsPerPage: number }) {
+  page.value = options.page
+  itemsPerPage.value = options.itemsPerPage
+
+  // Ignore the initial emit fired while the table mounts; onMounted owns the
+  // first fetch so the request is not duplicated.
+  if (!initialLoadComplete.value) {
+    return
+  }
+  fetchContacts()
+}
+
 watch(
   () => contactsStore.search,
   () => {
@@ -307,17 +336,22 @@ watch(
       clearTimeout(searchTimer)
     }
     searchTimer = setTimeout(() => {
-      contactsStore.loadContacts(true).catch(() => {
-        // The store already surfaced the failure via a notification.
-      })
+      // A new query always resets to the first page. If we are already on
+      // page 1 the page ref does not change, so no @update:options fires and
+      // we fetch directly; otherwise resetting the page drives the fetch via
+      // onUpdateOptions. Either way exactly one request is made.
+      if (page.value !== 1) {
+        page.value = 1
+      } else {
+        fetchContacts()
+      }
     }, 350)
   },
 )
 
 onMounted(() => {
-  contactsStore.loadContacts(true).catch(() => {
-    // The store already surfaced the failure via a notification.
-  })
+  initialLoadComplete.value = true
+  fetchContacts()
 })
 
 onBeforeUnmount(() => {
@@ -386,15 +420,18 @@ onBeforeUnmount(() => {
           />
 
           <VCard variant="outlined">
-            <VDataTable
+            <VDataTableServer
+              v-model:page="page"
+              v-model:items-per-page="itemsPerPage"
               :headers="headers"
               :items="contactsStore.contacts"
+              :items-length="contactsStore.total"
               :loading="contactsStore.loading"
-              :items-per-page="10"
               :items-per-page-options="itemsPerPageOptions"
               item-value="id"
               hover
               loading-text="Loading contacts…"
+              @update:options="onUpdateOptions"
             >
               <template #[`item.name`]="{ item }">
                 <div class="d-flex align-center py-2">
@@ -416,11 +453,11 @@ onBeforeUnmount(() => {
 
               <template #[`item.phone_numbers`]="{ item }">
                 <div
-                  v-if="item.phone_numbers.length"
+                  v-if="item.phone_numbers?.length"
                   class="d-flex flex-column ga-1 py-2"
                 >
                   <VChip
-                    v-for="phone in item.phone_numbers"
+                    v-for="phone in item.phone_numbers ?? []"
                     :key="phone"
                     size="small"
                     variant="tonal"
@@ -435,11 +472,11 @@ onBeforeUnmount(() => {
 
               <template #[`item.emails`]="{ item }">
                 <div
-                  v-if="item.emails.length"
+                  v-if="item.emails?.length"
                   class="d-flex flex-column ga-1 py-2"
                 >
                   <span
-                    v-for="email in item.emails"
+                    v-for="email in item.emails ?? []"
                     :key="email"
                     class="d-flex align-center text-body-2"
                   >
@@ -518,7 +555,7 @@ onBeforeUnmount(() => {
                   </VBtn>
                 </div>
               </template>
-            </VDataTable>
+            </VDataTableServer>
           </VCard>
         </VCol>
       </VRow>
diff --git a/web/app/stores/contacts.ts b/web/app/stores/contacts.ts
index 9bf3e3b74..9ea0a75fa 100644
--- a/web/app/stores/contacts.ts
+++ b/web/app/stores/contacts.ts
@@ -1,5 +1,5 @@
 import { defineStore } from 'pinia'
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 import type { EntitiesContact } from '~~/shared/types/api'
 import { getApiErrorMessage } from '~/utils/api-error'
 
@@ -10,50 +10,71 @@ export interface ContactInput {
   properties?: Record<string, string>
 }
 
+export interface LoadContactsOptions {
+  force?: boolean
+  skip?: number
+  limit?: number
+}
+
+// DEFAULT_LIMIT mirrors the contacts page's initial items-per-page. It is only
+// used when a caller (e.g. a mutation refresh) does not specify its own limit.
+const DEFAULT_LIMIT = 10
+
 export const useContactsStore = defineStore('contacts', () => {
   const contacts = ref<EntitiesContact[]>([])
+  const total = ref(0)
   const loading = ref(false)
   const search = ref('')
   const { apiFetch } = useApi()
   const notificationsStore = useNotificationsStore()
   let loadContactsGeneration = 0
 
-  const total = computed(() => contacts.value.length)
+  // The pagination window last requested by the page. Mutation-triggered
+  // refreshes reuse it so the user stays on the page they were viewing.
+  let currentSkip = 0
+  let currentLimit = DEFAULT_LIMIT
 
-  const filteredContacts = computed<EntitiesContact[]>(() => {
-    const term = search.value.trim().toLowerCase()
-    if (!term) return contacts.value
+  function normalizeOptions(
+    options: LoadContactsOptions | boolean,
+  ): LoadContactsOptions {
+    if (typeof options === 'boolean') {
+      return { force: options }
+    }
+    return options
+  }
 
-    return contacts.value.filter((contact) => {
-      const name = contact.name.toLowerCase()
-      const emails = contact.emails.join(' ').toLowerCase()
-      const phoneNumbers = contact.phone_numbers.join(' ').toLowerCase()
+  async function loadContacts(
+    options: LoadContactsOptions | boolean = {},
+  ): Promise<void> {
+    const { force = false, skip, limit } = normalizeOptions(options)
 
-      return (
-        name.includes(term) ||
-        emails.includes(term) ||
-        phoneNumbers.includes(term)
-      )
-    })
-  })
+    if (skip !== undefined) {
+      currentSkip = skip
+    }
+    if (limit !== undefined) {
+      currentLimit = limit
+    }
 
-  async function loadContacts(force = false): Promise<void> {
     if (contacts.value.length > 0 && !force) return
 
     const generation = ++loadContactsGeneration
     loading.value = true
     try {
       const term = search.value.trim()
-      const params: Record<string, string | number> = { limit: 100 }
+      const params: Record<string, string | number> = {
+        skip: currentSkip,
+        limit: currentLimit,
+      }
       if (term) {
         params.query = term
       }
-      const response = await apiFetch<{ data: EntitiesContact[] }>(
-        '/v1/contacts',
-        { params },
-      )
+      const response = await apiFetch<{
+        data: EntitiesContact[]
+        total?: number
+      }>('/v1/contacts', { params })
       if (generation === loadContactsGeneration) {
         contacts.value = response.data ?? []
+        total.value = response.total ?? contacts.value.length
       }
     } catch (error: unknown) {
       if (generation !== loadContactsGeneration) {
@@ -135,7 +156,12 @@ export const useContactsStore = defineStore('contacts', () => {
     loading.value = true
     try {
       await apiFetch(`/v1/contacts/${id}`, { method: 'DELETE' })
+      // Invalidate any in-flight load so a stale response cannot resurrect the
+      // just-deleted contact. Bumping the generation makes loadContacts skip
+      // its assignment (and its finally toggling loading) for the older request.
+      loadContactsGeneration++
       contacts.value = contacts.value.filter((contact) => contact.id !== id)
+      total.value = Math.max(0, total.value - 1)
       notificationsStore.addNotification({
         message: 'Contact deleted',
         type: 'success',
@@ -183,16 +209,18 @@ export const useContactsStore = defineStore('contacts', () => {
   function resetState() {
     loadContactsGeneration++
     contacts.value = []
+    total.value = 0
     loading.value = false
     search.value = ''
+    currentSkip = 0
+    currentLimit = DEFAULT_LIMIT
   }
 
   return {
     contacts,
+    total,
     loading,
     search,
-    total,
-    filteredContacts,
     loadContacts,
     saveContacts,
     updateContact,
diff --git a/web/shared/types/api.ts b/web/shared/types/api.ts
index c32224525..4f8d1d0fd 100644
--- a/web/shared/types/api.ts
+++ b/web/shared/types/api.ts
@@ -679,6 +679,12 @@ export interface ResponsesContactsResponse {
   message: string;
   /** @example "success" */
   status: string;
+  /**
+   * Total is the number of contacts matching the request filter for the
+   * user, independent of the pagination skip/limit applied to Data.
+   * @example 57
+   */
+  total: number;
 }
 
 export interface ResponsesDiscordResponse {

From e942b9886d509c057084bd735d23d1e3e187f416 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Mon, 20 Jul 2026 01:04:01 +0300
Subject: [PATCH 23/24] fix(web): mark contacts headers unsortable

Remove misleading sort affordances from the contacts table.

Keep the subtitle aligned with the active search state.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 web/app/pages/contacts/index.vue | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/web/app/pages/contacts/index.vue b/web/app/pages/contacts/index.vue
index 3d0ce297a..342c71204 100644
--- a/web/app/pages/contacts/index.vue
+++ b/web/app/pages/contacts/index.vue
@@ -49,11 +49,11 @@ const { formatPhoneNumber, humanizeTime, formatTimestamp } = useFilters()
 const avatarPalette = ['primary', 'secondary', 'info', 'success']
 
 const headers = [
-  { title: 'Name', key: 'name', sortable: true },
+  { title: 'Name', key: 'name', sortable: false },
   { title: 'Phone Numbers', key: 'phone_numbers', sortable: false },
   { title: 'Emails', key: 'emails', sortable: false },
-  { title: 'Created', key: 'created_at', sortable: true },
-  { title: 'Updated', key: 'updated_at', sortable: true },
+  { title: 'Created', key: 'created_at', sortable: false },
+  { title: 'Updated', key: 'updated_at', sortable: false },
   { title: 'Actions', key: 'actions', sortable: false, align: 'end' as const },
 ]
 
@@ -99,6 +99,8 @@ const searchTerm = computed({
   },
 })
 
+const trimmedSearchTerm = computed(() => contactsStore.search.trim())
+
 const dialogTitle = computed(() =>
   editingId.value ? 'Edit Contact' : 'Add Contact',
 )
@@ -384,7 +386,12 @@ onBeforeUnmount(() => {
             <div>
               <h1 class="text-display-large mb-1">Contacts</h1>
               <p class="text-medium-emphasis mb-0">
-                Manage your contacts. {{ contactsStore.total }} total
+                Manage your contacts.
+                {{
+                  trimmedSearchTerm
+                    ? `${contactsStore.total} found`
+                    : `${contactsStore.total} total`
+                }}
               </p>
             </div>
             <VSpacer />

From eb42cfffa490818a65fc8a21ca510f743d8a56d9 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Tue, 21 Jul 2026 10:24:12 +0300
Subject: [PATCH 24/24] test: add contacts integration coverage

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f3addc9-71dd-4cb7-bfae-e6fdcc8511af
---
 tests/README.md                    |   1 +
 tests/contacts_integration_test.go | 332 +++++++++++++++++++++++++++++
 2 files changed, 333 insertions(+)
 create mode 100644 tests/contacts_integration_test.go

diff --git a/tests/README.md b/tests/README.md
index 45bbb278f..20e4f5e12 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -55,6 +55,7 @@ The API's Firebase SDK is configured (via `FCM_ENDPOINT` env var) to redirect al
 - [x] **Receive SMS E2E** — Phone submits received message to API → message is stored and retrievable via GET endpoint
 - [x] **Message thread read receipts E2E** — Incoming SMS and missed calls mark a thread unread, the existing thread update endpoint marks it read, and outbound activity preserves unread state
 - [x] **Unarchive Thread on Receive E2E** — Archived thread returns to the inbox on inbound message when the phone's `unarchive_thread` setting is enabled, and stays archived when disabled
+- [x] **Contacts E2E** — JSON CRUD, search and pagination totals, CSV import normalization, and contact details attached to message threads
 
 ## Prerequisites
 
diff --git a/tests/contacts_integration_test.go b/tests/contacts_integration_test.go
new file mode 100644
index 000000000..2dcd4d5c0
--- /dev/null
+++ b/tests/contacts_integration_test.go
@@ -0,0 +1,332 @@
+package tests
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type integrationContact struct {
+	ID           string            `json:"id"`
+	Name         string            `json:"name"`
+	Emails       []string          `json:"emails"`
+	PhoneNumbers []string          `json:"phone_numbers"`
+	Properties   map[string]string `json:"properties"`
+}
+
+type integrationContactsResponse struct {
+	Data  []integrationContact `json:"data"`
+	Total int64                `json:"total"`
+}
+
+type integrationContactResponse struct {
+	Data integrationContact `json:"data"`
+}
+
+type integrationContactThread struct {
+	ID             string              `json:"id"`
+	Contact        string              `json:"contact"`
+	ContactDetails *integrationContact `json:"contact_details"`
+}
+
+func createIntegrationContacts(
+	ctx context.Context,
+	t *testing.T,
+	contacts []map[string]any,
+) []integrationContact {
+	t.Helper()
+
+	var response integrationContactsResponse
+	requestJSON(
+		ctx,
+		t,
+		http.MethodPost,
+		"/v1/contacts",
+		userAPIKey,
+		contacts,
+		http.StatusCreated,
+		&response,
+	)
+	require.Len(t, response.Data, len(contacts))
+	return response.Data
+}
+
+func deleteIntegrationContact(ctx context.Context, t *testing.T, contactID string) {
+	t.Helper()
+
+	requestJSON(
+		ctx,
+		t,
+		http.MethodDelete,
+		"/v1/contacts/"+contactID,
+		userAPIKey,
+		nil,
+		http.StatusNoContent,
+		nil,
+	)
+}
+
+func cleanupIntegrationContact(t *testing.T, contactID string) {
+	t.Helper()
+
+	request, err := http.NewRequest(
+		http.MethodDelete,
+		apiBaseURL+"/v1/contacts/"+contactID,
+		nil,
+	)
+	require.NoError(t, err)
+	request.Header.Set("x-api-key", userAPIKey)
+
+	response, err := http.DefaultClient.Do(request)
+	require.NoError(t, err)
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	require.NoError(t, err)
+	require.Contains(
+		t,
+		[]int{http.StatusNoContent, http.StatusNotFound},
+		response.StatusCode,
+		"response: %s",
+		string(responseBody),
+	)
+}
+
+func listIntegrationContacts(
+	ctx context.Context,
+	t *testing.T,
+	query string,
+	skip int,
+	limit int,
+) integrationContactsResponse {
+	t.Helper()
+
+	path := fmt.Sprintf(
+		"/v1/contacts?query=%s&skip=%d&limit=%d",
+		url.QueryEscape(query),
+		skip,
+		limit,
+	)
+	var response integrationContactsResponse
+	requestJSON(ctx, t, http.MethodGet, path, userAPIKey, nil, http.StatusOK, &response)
+	return response
+}
+
+func uploadIntegrationContactsCSV(
+	ctx context.Context,
+	t *testing.T,
+	contents string,
+) integrationContactsResponse {
+	t.Helper()
+
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	part, err := writer.CreateFormFile("document", "contacts.csv")
+	require.NoError(t, err)
+	_, err = part.Write([]byte(contents))
+	require.NoError(t, err)
+	require.NoError(t, writer.Close())
+
+	request, err := http.NewRequestWithContext(
+		ctx,
+		http.MethodPost,
+		apiBaseURL+"/v1/contacts/upload",
+		&body,
+	)
+	require.NoError(t, err)
+	request.Header.Set("x-api-key", userAPIKey)
+	request.Header.Set("Content-Type", writer.FormDataContentType())
+
+	response, err := http.DefaultClient.Do(request)
+	require.NoError(t, err)
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	require.NoError(t, err)
+	require.Equal(t, http.StatusCreated, response.StatusCode, "response: %s", string(responseBody))
+
+	var result integrationContactsResponse
+	require.NoError(t, json.Unmarshal(responseBody, &result))
+	return result
+}
+
+func waitForThreadWithContact(
+	ctx context.Context,
+	t *testing.T,
+	owner string,
+	phoneNumber string,
+	timeout time.Duration,
+) integrationContactThread {
+	t.Helper()
+
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		path := fmt.Sprintf(
+			"/v1/message-threads?owner=%s&contacts=true&skip=0&limit=20",
+			url.QueryEscape(owner),
+		)
+		var response struct {
+			Data []integrationContactThread `json:"data"`
+		}
+		requestJSON(ctx, t, http.MethodGet, path, userAPIKey, nil, http.StatusOK, &response)
+		for _, thread := range response.Data {
+			if thread.Contact == phoneNumber && thread.ContactDetails != nil {
+				return thread
+			}
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	t.Fatalf("thread for %s did not include contact details within %v", phoneNumber, timeout)
+	return integrationContactThread{}
+}
+
+func TestContacts_CRUDSearchAndPagination(t *testing.T) {
+	ctx := context.Background()
+	marker := strings.ToLower(uuid.New().String())
+	firstPhone := randomPhoneNumber()
+	secondPhone := randomPhoneNumber()
+
+	created := createIntegrationContacts(ctx, t, []map[string]any{
+		{
+			"name":          "  Alice " + marker + "  ",
+			"emails":        []string{" ALICE-" + marker + "@EXAMPLE.COM "},
+			"phone_numbers": []string{strings.TrimPrefix(firstPhone, "+")},
+			"properties":    map[string]string{"company": "Acme"},
+		},
+		{
+			"name":          "Bob " + marker,
+			"emails":        []string{"bob-" + marker + "@example.com"},
+			"phone_numbers": []string{secondPhone},
+		},
+	})
+	for _, contact := range created {
+		contactID := contact.ID
+		t.Cleanup(func() {
+			cleanupIntegrationContact(t, contactID)
+		})
+	}
+
+	require.Len(t, created, 2)
+	assert.Equal(t, "Alice "+marker, created[0].Name)
+	assert.Equal(t, []string{"alice-" + marker + "@example.com"}, created[0].Emails)
+	assert.Equal(t, []string{firstPhone}, created[0].PhoneNumbers)
+	assert.Equal(t, map[string]string{"company": "Acme"}, created[0].Properties)
+
+	page := listIntegrationContacts(ctx, t, marker, 0, 1)
+	assert.EqualValues(t, 2, page.Total)
+	require.Len(t, page.Data, 1)
+
+	emailMatch := listIntegrationContacts(ctx, t, "ALICE-"+marker+"@EXAMPLE.COM", 0, 20)
+	assert.EqualValues(t, 1, emailMatch.Total)
+	require.Len(t, emailMatch.Data, 1)
+	assert.Equal(t, created[0].ID, emailMatch.Data[0].ID)
+
+	var updated integrationContactResponse
+	requestJSON(
+		ctx,
+		t,
+		http.MethodPut,
+		"/v1/contacts/"+created[0].ID,
+		userAPIKey,
+		map[string]any{
+			"name":          "Updated " + marker,
+			"emails":        []string{"updated-" + marker + "@example.com"},
+			"phone_numbers": []string{firstPhone},
+			"properties":    map[string]string{"company": "NdoleStudio"},
+		},
+		http.StatusOK,
+		&updated,
+	)
+	assert.Equal(t, "Updated "+marker, updated.Data.Name)
+	assert.Equal(t, []string{"updated-" + marker + "@example.com"}, updated.Data.Emails)
+	assert.Equal(t, map[string]string{"company": "NdoleStudio"}, updated.Data.Properties)
+
+	deleteIntegrationContact(ctx, t, created[0].ID)
+
+	deletedMatch := listIntegrationContacts(ctx, t, "updated-"+marker+"@example.com", 0, 20)
+	assert.Zero(t, deletedMatch.Total)
+	assert.Empty(t, deletedMatch.Data)
+}
+
+func TestContacts_CSVUpload(t *testing.T) {
+	ctx := context.Background()
+	marker := strings.ToLower(uuid.New().String())
+	phoneNumber := randomPhoneNumber()
+	csv := fmt.Sprintf(
+		"Name,Emails,PhoneNumbers\nCSV %s,\"FIRST-%s@EXAMPLE.COM;second-%s@example.com\",%s\n",
+		marker,
+		marker,
+		marker,
+		strings.TrimPrefix(phoneNumber, "+"),
+	)
+
+	response := uploadIntegrationContactsCSV(ctx, t, csv)
+	require.Len(t, response.Data, 1)
+	contact := response.Data[0]
+	t.Cleanup(func() {
+		cleanupIntegrationContact(t, contact.ID)
+	})
+
+	assert.Equal(t, "CSV "+marker, contact.Name)
+	assert.Equal(t, []string{
+		"first-" + marker + "@example.com",
+		"second-" + marker + "@example.com",
+	}, contact.Emails)
+	assert.Equal(t, []string{phoneNumber}, contact.PhoneNumbers)
+
+	listed := listIntegrationContacts(ctx, t, marker, 0, 20)
+	assert.EqualValues(t, 1, listed.Total)
+	require.Len(t, listed.Data, 1)
+	assert.Equal(t, contact.ID, listed.Data[0].ID)
+}
+
+func TestContacts_MessageThreadsIncludeContactDetails(t *testing.T) {
+	ctx := context.Background()
+	phone := setupPhone(ctx, t, 60)
+	contactPhone := randomPhoneNumber()
+	marker := strings.ToLower(uuid.New().String())
+
+	created := createIntegrationContacts(ctx, t, []map[string]any{
+		{
+			"name":          "Thread Contact " + marker,
+			"emails":        []string{"thread-" + marker + "@example.com"},
+			"phone_numbers": []string{contactPhone},
+			"properties":    map[string]string{"source": "integration-test"},
+		},
+	})
+	contact := created[0]
+	t.Cleanup(func() {
+		cleanupIntegrationContact(t, contact.ID)
+	})
+
+	messageID := receiveInbound(
+		ctx,
+		t,
+		phone.PhoneAPIKey,
+		contactPhone,
+		phone.PhoneNumber,
+		"Contact enrichment "+marker,
+		time.Now(),
+	)
+	pollMessageStatus(ctx, t, messageID, "received", 15*time.Second)
+
+	thread := waitForThreadWithContact(ctx, t, phone.PhoneNumber, contactPhone, 20*time.Second)
+	require.NotNil(t, thread.ContactDetails)
+	assert.Equal(t, contact.ID, thread.ContactDetails.ID)
+	assert.Equal(t, contact.Name, thread.ContactDetails.Name)
+	assert.Equal(t, contact.PhoneNumbers, thread.ContactDetails.PhoneNumbers)
+	assert.Equal(t, contact.Properties, thread.ContactDetails.Properties)
+}