feat: add contacts management and thread resolution

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()
 
@@ -414,6 +416,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
 }
 
@@ -697,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))
@@ -895,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") {
@@ -1110,6 +1146,18 @@ func (container *Container) MessageThreadService() (service *services.MessageThr
 		container.MessageThreadRepository(),
 		container.PhoneRepository(),
 		container.EventDispatcher(),
+		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(),
 	)
 }
 
@@ -1664,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{}))

api/pkg/entities/contact.go

@@ -0,0 +1,76 @@
+package entities
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"time"
+
+	"github.com/NdoleStudio/stacktrace"
+	"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, stacktrace.Propagatef(err, "cannot marshal ContactProperties")
+	}
+
+	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 stacktrace.NewErrorf("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 stacktrace.Propagatef(err, "cannot unmarshal ContactProperties")
+	}
+
+	*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"
+}

api/pkg/entities/contact_test.go

@@ -0,0 +1,50 @@
+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))
+}
+
+func TestContactProperties_ScanUnsupportedType(t *testing.T) {
+	var scanned ContactProperties
+
+	err := scanned.Scan(123)
+
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "unsupported type [int] for ContactProperties")
+}

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

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")
+}