Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
feat: add message thread read receipts (#956)
Acho Arnoldc36e30f3a949
diff --git a/api/docs/docs.go b/api/docs/docs.goindex c7fcd114..8cd408cb 100644--- a/api/docs/docs.go+++ b/api/docs/docs.go@@ -871,7 +871,7 @@ const docTemplate = `{"200": {"description": "OK","schema": {- "$ref": "#/definitions/responses.PhoneResponse"+ "$ref": "#/definitions/responses.MessageThreadResponse"}},"400": {@@ -886,6 +886,12 @@ const docTemplate = `{"$ref": "#/definitions/responses.Unauthorized"}},+ "404": {+ "description": "Not Found",+ "schema": {+ "$ref": "#/definitions/responses.NotFound"+ }+ },"422": {"description": "Unprocessable Entity","schema": {@@ -3691,6 +3697,7 @@ const docTemplate = `{"created_at","id","is_archived",+ "is_read","last_message_content","last_message_id","order_timestamp",@@ -3720,6 +3727,10 @@ const docTemplate = `{"type": "boolean","example": false},+ "is_read": {+ "type": "boolean",+ "example": true+ },"last_message_content": {"type": "string","example": "This is a sample message content"@@ -4388,13 +4399,14 @@ const docTemplate = `{},"requests.MessageThreadUpdate": {"type": "object",- "required": [- "is_archived"- ],"properties": {"is_archived": {"type": "boolean","example": true+ },+ "is_read": {+ "type": "boolean",+ "example": true}}},@@ -4904,6 +4916,27 @@ const docTemplate = `{}}},+ "responses.MessageThreadResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status"+ ],+ "properties": {+ "data": {+ "$ref": "#/definitions/entities.MessageThread"+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ }+ }+ },"responses.MessageThreadsResponse": {"type": "object","required": [diff --git a/api/docs/swagger.json b/api/docs/swagger.jsonindex 25db6fc3..ac9c12c9 100644--- a/api/docs/swagger.json+++ b/api/docs/swagger.json@@ -868,7 +868,7 @@"200": {"description": "OK","schema": {- "$ref": "#/definitions/responses.PhoneResponse"+ "$ref": "#/definitions/responses.MessageThreadResponse"}},"400": {@@ -883,6 +883,12 @@"$ref": "#/definitions/responses.Unauthorized"}},+ "404": {+ "description": "Not Found",+ "schema": {+ "$ref": "#/definitions/responses.NotFound"+ }+ },"422": {"description": "Unprocessable Entity","schema": {@@ -3688,6 +3694,7 @@"created_at","id","is_archived",+ "is_read","last_message_content","last_message_id","order_timestamp",@@ -3717,6 +3724,10 @@"type": "boolean","example": false},+ "is_read": {+ "type": "boolean",+ "example": true+ },"last_message_content": {"type": "string","example": "This is a sample message content"@@ -4385,13 +4396,14 @@},"requests.MessageThreadUpdate": {"type": "object",- "required": [- "is_archived"- ],"properties": {"is_archived": {"type": "boolean","example": true+ },+ "is_read": {+ "type": "boolean",+ "example": true}}},@@ -4901,6 +4913,27 @@}}},+ "responses.MessageThreadResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status"+ ],+ "properties": {+ "data": {+ "$ref": "#/definitions/entities.MessageThread"+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ }+ }+ },"responses.MessageThreadsResponse": {"type": "object","required": [diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yamlindex 892c9ae4..ddc6ae70 100644--- a/api/docs/swagger.yaml+++ b/api/docs/swagger.yaml@@ -319,6 +319,9 @@ definitions:is_archived:example: falsetype: boolean+ is_read:+ example: true+ type: booleanlast_message_content:example: This is a sample message contenttype: string@@ -346,6 +349,7 @@ definitions:- created_at- id- is_archived+ - is_read- last_message_content- last_message_id- order_timestamp@@ -853,8 +857,9 @@ definitions:is_archived:example: truetype: boolean- required:- - is_archived+ is_read:+ example: true+ type: booleantype: objectrequests.PhoneAPIKeyStoreRequest:properties:@@ -1227,6 +1232,21 @@ definitions:- message- statustype: object+ responses.MessageThreadResponse:+ properties:+ data:+ $ref: '#/definitions/entities.MessageThread'+ message:+ example: Request handled successfully+ type: string+ status:+ example: success+ type: string+ required:+ - data+ - message+ - status+ type: objectresponses.MessageThreadsResponse:properties:data:@@ -2182,7 +2202,7 @@ paths:"200":description: OKschema:- $ref: '#/definitions/responses.PhoneResponse'+ $ref: '#/definitions/responses.MessageThreadResponse'"400":description: Bad Requestschema:@@ -2191,6 +2211,10 @@ paths:description: Unauthorizedschema:$ref: '#/definitions/responses.Unauthorized'+ "404":+ description: Not Found+ schema:+ $ref: '#/definitions/responses.NotFound'"422":description: Unprocessable Entityschema:diff --git a/api/pkg/entities/message_thread.go b/api/pkg/entities/message_thread.goindex 2eb1e2d3..3766acc7 100644--- a/api/pkg/entities/message_thread.go+++ b/api/pkg/entities/message_thread.go@@ -12,6 +12,8 @@ type MessageThread struct {Owner string `json:"owner" example:"+18005550199"`Contact string `json:"contact" example:"+18005550100"`IsArchived bool `json:"is_archived" example:"false"`+ IsRead bool `json:"is_read" gorm:"not null;default:true" example:"true"`+ LastReadAt time.Time `json:"-" gorm:"not null;default:CURRENT_TIMESTAMP"`UserID UserID `json:"user_id" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`Color string `json:"color" example:"indigo"`Status MessageStatus `json:"status" example:"PENDING"`diff --git a/api/pkg/entities/message_thread_test.go b/api/pkg/entities/message_thread_test.gonew file mode 100644index 00000000..1409dff2--- /dev/null+++ b/api/pkg/entities/message_thread_test.go@@ -0,0 +1,25 @@+package entities++import (+ "reflect"+ "testing"++ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestMessageThreadReadFieldsHaveBackwardCompatibleDefaults(t *testing.T) {+ threadType := reflect.TypeOf(MessageThread{})++ isRead, ok := threadType.FieldByName("IsRead")+ require.True(t, ok)+ assert.Contains(t, isRead.Tag.Get("gorm"), "not null")+ assert.Contains(t, isRead.Tag.Get("gorm"), "default:true")+ assert.Equal(t, "is_read", isRead.Tag.Get("json"))++ lastReadAt, ok := threadType.FieldByName("LastReadAt")+ require.True(t, ok)+ assert.Contains(t, lastReadAt.Tag.Get("gorm"), "not null")+ assert.Contains(t, lastReadAt.Tag.Get("gorm"), "default:CURRENT_TIMESTAMP")+ assert.Equal(t, "-", lastReadAt.Tag.Get("json"))+}diff --git a/api/pkg/handlers/message_thread_handler.go b/api/pkg/handlers/message_thread_handler.goindex 1a00f773..9520b663 100644--- a/api/pkg/handlers/message_thread_handler.go+++ b/api/pkg/handlers/message_thread_handler.go@@ -100,9 +100,10 @@ func (h *MessageThreadHandler) Index(c fiber.Ctx) error {// @Produce json// @Param messageThreadID path string true "ID of the message thread" default(32343a19-da5e-4b1b-a767-3298a73703ca)// @Param payload body requests.MessageThreadUpdate true "Payload of message thread details to update"-// @Success 200 {object} responses.PhoneResponse+// @Success 200 {object} responses.MessageThreadResponse// @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 /message-threads/{messageThreadID} [put]@@ -123,6 +124,9 @@ func (h *MessageThreadHandler) Update(c fiber.Ctx) error {}thread, err := h.service.UpdateStatus(ctx, request.ToUpdateParams(h.userIDFomContext(c)))+ if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {+ return h.responseNotFound(c, fmt.Sprintf("cannot find message thread with ID [%s]", request.MessageThreadID))+ }if err != nil {ctxLogger.Error(stacktrace.Propagate(err, "cannot update message thread with params [%+#v]", request))return h.responseInternalServerError(c)diff --git a/api/pkg/handlers/message_thread_handler_test.go b/api/pkg/handlers/message_thread_handler_test.gonew file mode 100644index 00000000..ab2d7596--- /dev/null+++ b/api/pkg/handlers/message_thread_handler_test.go@@ -0,0 +1,110 @@+package handlers++import (+ "bytes"+ "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/palantir/stacktrace"+ "github.com/stretchr/testify/require"+ "go.opentelemetry.io/otel/trace"+ "gorm.io/gorm"+)++type messageThreadHandlerRepositoryStub struct{}++func (stub *messageThreadHandlerRepositoryStub) Store(context.Context, *entities.MessageThread) error {+ return nil+}++func (stub *messageThreadHandlerRepositoryStub) UpdateActivity(context.Context, repositories.MessageThreadActivityUpdate) error {+ return nil+}++func (stub *messageThreadHandlerRepositoryStub) UpdateStatus(context.Context, entities.UserID, uuid.UUID, repositories.MessageThreadStatusUpdate) (*entities.MessageThread, error) {+ return nil, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found")+}++func (stub *messageThreadHandlerRepositoryStub) LoadByOwnerContact(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return nil, nil+}++func (stub *messageThreadHandlerRepositoryStub) Load(context.Context, entities.UserID, uuid.UUID) (*entities.MessageThread, error) {+ return nil, nil+}++func (stub *messageThreadHandlerRepositoryStub) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {+ return nil, nil+}++func (stub *messageThreadHandlerRepositoryStub) UpdateAfterDeletedMessage(context.Context, repositories.MessageThreadDeletedUpdate) error {+ return nil+}++func (stub *messageThreadHandlerRepositoryStub) Delete(context.Context, entities.UserID, uuid.UUID) error {+ return nil+}++func (stub *messageThreadHandlerRepositoryStub) DeleteAllForUser(context.Context, entities.UserID) error {+ return nil+}++func TestMessageThreadHandlerUpdate_ReturnsNotFoundWhenThreadIsMissing(t *testing.T) {+ logger := &messageThreadHandlerNoopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ service := services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil)+ 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: "[email protected]"})+ return c.Next()+ })+ handler.RegisterRoutes(app)++ messageThreadID := uuid.New()+ req := httptest.NewRequest(http.MethodPut, "/v1/message-threads/"+messageThreadID.String(), bytes.NewBufferString(`{"is_read":true}`))+ 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)++ var payload struct {+ Message string `json:"message"`+ }+ require.NoError(t, json.NewDecoder(resp.Body).Decode(&payload))+ require.Equal(t, "cannot find message thread with ID ["+messageThreadID.String()+"]", payload.Message)+}++type messageThreadHandlerNoopLogger struct{}++var _ telemetry.Logger = (*messageThreadHandlerNoopLogger)(nil)++func (logger *messageThreadHandlerNoopLogger) Error(_ error) {}+func (logger *messageThreadHandlerNoopLogger) WithService(_ string) telemetry.Logger { return logger }++func (logger *messageThreadHandlerNoopLogger) WithString(_, _ string) telemetry.Logger { return logger }++func (logger *messageThreadHandlerNoopLogger) WithSpan(_ trace.SpanContext) telemetry.Logger {+ return logger+}+func (logger *messageThreadHandlerNoopLogger) Trace(_ string) {}+func (logger *messageThreadHandlerNoopLogger) Info(_ string) {}+func (logger *messageThreadHandlerNoopLogger) Warn(_ error) {}+func (logger *messageThreadHandlerNoopLogger) Debug(_ string) {}+func (logger *messageThreadHandlerNoopLogger) Fatal(_ error) {}+func (logger *messageThreadHandlerNoopLogger) Printf(_ string, _ ...interface{}) {}diff --git a/api/pkg/listeners/message_thread_listener.go b/api/pkg/listeners/message_thread_listener.goindex e5f90ca3..47621296 100644--- a/api/pkg/listeners/message_thread_listener.go+++ b/api/pkg/listeners/message_thread_listener.go@@ -40,6 +40,7 @@ func NewMessageThreadListener(events.EventTypeMessagePhoneDelivered: l.OnMessagePhoneDelivered,events.EventTypeMessageSendFailed: l.OnMessagePhoneFailed,events.EventTypeMessagePhoneReceived: l.OnMessagePhoneReceived,+ events.MessageCallMissed: l.OnMessageCallMissed,events.EventTypeMessageNotificationScheduled: l.onMessageNotificationScheduled,events.EventTypeMessageSendExpired: l.onMessageExpired,events.UserAccountDeleted: l.onUserAccountDeleted,@@ -209,13 +210,15 @@ func (listener *MessageThreadListener) OnMessagePhoneReceived(ctx context.Contex}updateParams := services.MessageThreadUpdateParams{- Owner: payload.Owner,- Contact: payload.Contact,- Timestamp: payload.Timestamp,- UserID: payload.UserID,- Status: entities.MessageStatusReceived,- Content: payload.Content,- MessageID: payload.MessageID,+ Owner: payload.Owner,+ Contact: payload.Contact,+ Timestamp: payload.Timestamp,+ UserID: payload.UserID,+ Status: entities.MessageStatusReceived,+ Content: payload.Content,+ MessageID: payload.MessageID,+ MarkAsUnread: true,+ EventTimestamp: event.Time(),}if err := listener.service.UpdateThread(ctx, updateParams); err != nil {@@ -225,6 +228,33 @@ func (listener *MessageThreadListener) OnMessagePhoneReceived(ctx context.Contexreturn nil}+// OnMessageCallMissed handles the events.MessageCallMissed event+func (listener *MessageThreadListener) OnMessageCallMissed(ctx context.Context, event cloudevents.Event) error {+ ctx, span := listener.tracer.Start(ctx)+ defer span.End()++ var payload events.MessageCallMissedPayload+ if err := event.DataAs(&payload); err != nil {+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot decode [%s] into [%T]", event.Data(), payload))+ }++ params := services.MessageThreadUpdateParams{+ Owner: payload.Owner,+ Contact: payload.Contact,+ UserID: payload.UserID,+ Status: entities.MessageStatusReceived,+ Timestamp: payload.Timestamp,+ Content: "Missed phone call",+ MessageID: payload.MessageID,+ MarkAsUnread: true,+ EventTimestamp: event.Time(),+ }+ if err := listener.service.UpdateThread(ctx, params); err != nil {+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot update thread for missed call [%s] on event [%s]", payload.MessageID, event.ID()))+ }+ return nil+}+// onMessageNotificationScheduled handles the events.EventTypeMessageNotificationScheduled eventfunc (listener *MessageThreadListener) onMessageNotificationScheduled(ctx context.Context, event cloudevents.Event) error {ctx, span := listener.tracer.Start(ctx)diff --git a/api/pkg/listeners/message_thread_listener_test.go b/api/pkg/listeners/message_thread_listener_test.gonew file mode 100644index 00000000..39a444cc--- /dev/null+++ b/api/pkg/listeners/message_thread_listener_test.go@@ -0,0 +1,72 @@+package listeners++import (+ "context"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ cloudevents "github.com/cloudevents/sdk-go/v2"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestMessageThreadListenerMarksInboundMessageUnread(t *testing.T) {+ repository, routes := newMessageThreadListenerForTest()+ event := cloudevents.NewEvent()+ event.SetID(uuid.NewString())+ event.SetSource("/v1/messages/phone-received")+ event.SetType(events.EventTypeMessagePhoneReceived)+ event.SetTime(time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC))+ require.NoError(t, event.SetData(cloudevents.ApplicationJSON, events.MessagePhoneReceivedPayload{+ MessageID: uuid.New(),+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ Content: "hello",+ Timestamp: time.Date(2026, 7, 18, 6, 59, 0, 0, time.UTC),+ }))++ err := routes[events.EventTypeMessagePhoneReceived](context.Background(), event)++ require.NoError(t, err)+ assert.True(t, repository.activity.MarkAsUnread)+ assert.Equal(t, event.Time(), repository.activity.EventTimestamp)+}++func TestMessageThreadListenerMarksMissedCallUnread(t *testing.T) {+ repository, routes := newMessageThreadListenerForTest()+ event := cloudevents.NewEvent()+ event.SetID(uuid.NewString())+ event.SetSource("/v1/messages/call-missed")+ event.SetType(events.MessageCallMissed)+ event.SetTime(time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC))+ require.NoError(t, event.SetData(cloudevents.ApplicationJSON, events.MessageCallMissedPayload{+ MessageID: uuid.New(),+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ Timestamp: time.Date(2026, 7, 18, 6, 59, 0, 0, time.UTC),+ }))+ require.Contains(t, routes, events.MessageCallMissed)++ err := routes[events.MessageCallMissed](context.Background(), event)++ require.NoError(t, err)+ assert.True(t, repository.activity.MarkAsUnread)+ assert.Equal(t, "Missed phone call", repository.activity.Content)+ assert.Equal(t, event.Time(), repository.activity.EventTimestamp)+}++func newMessageThreadListenerForTest() (*listenerMessageThreadRepository, map[string]events.EventListener) {+ repository := &listenerMessageThreadRepository{}+ logger := &noopListenerLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ service := services.NewMessageThreadService(logger, tracer, repository, nil, nil)+ _, routes := NewMessageThreadListener(logger, tracer, service)+ return repository, routes+}diff --git a/api/pkg/listeners/read_receipts_test_helpers_test.go b/api/pkg/listeners/read_receipts_test_helpers_test.gonew file mode 100644index 00000000..60cd27e6--- /dev/null+++ b/api/pkg/listeners/read_receipts_test_helpers_test.go@@ -0,0 +1,66 @@+package listeners++import (+ "context"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/google/uuid"+ "go.opentelemetry.io/otel/trace"+)++type noopListenerLogger struct{}++func (logger *noopListenerLogger) Error(error) {}+func (logger *noopListenerLogger) WithService(string) telemetry.Logger { return logger }+func (logger *noopListenerLogger) WithString(string, string) telemetry.Logger { return logger }+func (logger *noopListenerLogger) WithSpan(trace.SpanContext) telemetry.Logger { return logger }+func (logger *noopListenerLogger) Trace(string) {}+func (logger *noopListenerLogger) Info(string) {}+func (logger *noopListenerLogger) Warn(error) {}+func (logger *noopListenerLogger) Debug(string) {}+func (logger *noopListenerLogger) Fatal(error) {}+func (logger *noopListenerLogger) Printf(string, ...interface{}) {}++type listenerMessageThreadRepository struct {+ activity repositories.MessageThreadActivityUpdate+}++func (repository *listenerMessageThreadRepository) Store(context.Context, *entities.MessageThread) error {+ return nil+}++func (repository *listenerMessageThreadRepository) UpdateActivity(_ context.Context, params repositories.MessageThreadActivityUpdate) error {+ repository.activity = params+ return nil+}++func (repository *listenerMessageThreadRepository) UpdateStatus(_ context.Context, _ entities.UserID, threadID uuid.UUID, _ repositories.MessageThreadStatusUpdate) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: threadID}, nil+}++func (repository *listenerMessageThreadRepository) UpdateAfterDeletedMessage(context.Context, repositories.MessageThreadDeletedUpdate) error {+ return nil+}++func (repository *listenerMessageThreadRepository) LoadByOwnerContact(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: uuid.New()}, nil+}++func (repository *listenerMessageThreadRepository) Load(context.Context, entities.UserID, uuid.UUID) (*entities.MessageThread, error) {+ return &entities.MessageThread{}, nil+}++func (repository *listenerMessageThreadRepository) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {+ threads := []entities.MessageThread{}+ return &threads, nil+}++func (repository *listenerMessageThreadRepository) Delete(context.Context, entities.UserID, uuid.UUID) error {+ return nil+}++func (repository *listenerMessageThreadRepository) DeleteAllForUser(context.Context, entities.UserID) error {+ return nil+}diff --git a/api/pkg/listeners/websocket_listener.go b/api/pkg/listeners/websocket_listener.goindex 3108ed67..8aa9054f 100644--- a/api/pkg/listeners/websocket_listener.go+++ b/api/pkg/listeners/websocket_listener.go@@ -36,9 +36,25 @@ func NewWebsocketListener(events.EventTypeMessagePhoneSent: l.onMessagePhoneSent,events.EventTypeMessageSendFailed: l.onMessagePhoneFailed,events.EventTypeMessagePhoneReceived: l.onMessagePhoneReceived,+ events.MessageCallMissed: l.onMessageCallMissed,}}+func (listener *WebsocketListener) onMessageCallMissed(ctx context.Context, event cloudevents.Event) error {+ ctx, span, _ := listener.tracer.StartWithLogger(ctx, listener.logger)+ defer span.End()++ var payload events.MessageCallMissedPayload+ if err := event.DataAs(&payload); err != nil {+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot decode [%s] into [%T]", event.Data(), payload))+ }++ if err := listener.client.Trigger(payload.UserID.String(), event.Type(), event.ID()); err != nil {+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot trigger websocket [%s] event with ID [%s] for user with ID [%s]", event.Type(), event.ID(), payload.UserID))+ }+ return nil+}+// onMessagePhoneSent handles the events.EventTypeMessagePhoneSent eventfunc (listener *WebsocketListener) onMessagePhoneSent(ctx context.Context, event cloudevents.Event) error {ctx, span, _ := listener.tracer.StartWithLogger(ctx, listener.logger)diff --git a/api/pkg/listeners/websocket_listener_test.go b/api/pkg/listeners/websocket_listener_test.gonew file mode 100644index 00000000..fdaf1c6d--- /dev/null+++ b/api/pkg/listeners/websocket_listener_test.go@@ -0,0 +1,18 @@+package listeners++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/pusher/pusher-http-go/v5"+ "github.com/stretchr/testify/assert"+)++func TestWebsocketListenerRegistersMissedCalls(t *testing.T) {+ logger := &noopListenerLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ _, routes := NewWebsocketListener(logger, tracer, &pusher.Client{})++ assert.Contains(t, routes, events.MessageCallMissed)+}diff --git a/api/pkg/repositories/gorm_message_thread_repository.go b/api/pkg/repositories/gorm_message_thread_repository.goindex 7bc07f7b..071f5cc7 100644--- a/api/pkg/repositories/gorm_message_thread_repository.go+++ b/api/pkg/repositories/gorm_message_thread_repository.go@@ -35,6 +35,48 @@ func NewGormMessageThreadRepository(}}+func messageThreadActivityUpdates(params MessageThreadActivityUpdate) map[string]any {+ updates := map[string]any{+ "order_timestamp": params.Timestamp,+ "last_message_id": params.MessageID,+ "last_message_content": params.Content,+ "status": params.Status,+ }+ if params.Unarchive {+ updates["is_archived"] = false+ }+ if params.MarkAsUnread {+ updates["is_read"] = gorm.Expr(+ "CASE WHEN last_read_at < ? THEN ? ELSE is_read END",+ params.EventTimestamp,+ false,+ )+ }+ return updates+}++func messageThreadDeletedUpdates(params MessageThreadDeletedUpdate) map[string]any {+ return map[string]any{+ "last_message_id": params.LastMessageID,+ "last_message_content": params.LastMessageContent,+ "status": params.LastMessageStatus,+ }+}++func messageThreadStatusUpdates(params MessageThreadStatusUpdate) map[string]any {+ updates := make(map[string]any)+ if params.IsArchived != nil {+ updates["is_archived"] = *params.IsArchived+ }+ if params.IsRead != nil {+ updates["is_read"] = *params.IsRead+ if *params.IsRead {+ updates["last_read_at"] = params.ReadAt+ }+ }+ return updates+}+func (repository *gormMessageThreadRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {ctx, span := repository.tracer.Start(ctx)defer span.End()@@ -60,20 +102,17 @@ func (repository *gormMessageThreadRepository) Delete(ctx context.Context, userI}// UpdateAfterDeletedMessage updates a thread after the original message has been deleted-func (repository *gormMessageThreadRepository) UpdateAfterDeletedMessage(ctx context.Context, userID entities.UserID, messageID uuid.UUID) error {+func (repository *gormMessageThreadRepository) UpdateAfterDeletedMessage(ctx context.Context, params MessageThreadDeletedUpdate) error {ctx, span := repository.tracer.Start(ctx)defer span.End()- err := repository.db.WithContext(ctx).Model(&entities.MessageThread{}).- Where("user_id = ?", userID).- Where("last_message_id = ?", messageID).- Updates(map[string]any{- "last_message_id": nil,- "last_message_content": nil,- "status": entities.MessageStatusDeleted,- }).Error- if err != nil {- return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot update thread after message is deleted with userID [%s] and messageID [%s]", userID, messageID))+ result := repository.db.WithContext(ctx).+ Model(&entities.MessageThread{}).+ Where("user_id = ?", params.UserID).+ Where("id = ?", params.MessageThreadID).+ Updates(messageThreadDeletedUpdates(params))+ if result.Error != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(result.Error, "cannot update deleted-message metadata for thread [%s]", params.MessageThreadID))}return nil@@ -84,25 +123,77 @@ func (repository *gormMessageThreadRepository) Store(ctx context.Context, threadctx, span := repository.tracer.Start(ctx)defer span.End()- if err := repository.db.WithContext(ctx).Clauses(clause.OnConflict{DoNothing: true}).Create(thread).Error; err != nil {+ isRead := thread.IsRead+ err := repository.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {+ result := tx.Clauses(clause.OnConflict{DoNothing: true}).Create(thread)+ thread.IsRead = isRead+ if result.Error != nil {+ return result.Error+ }+ if result.RowsAffected == 0 || isRead {+ return nil+ }++ return tx.Model(&entities.MessageThread{}).+ Where("user_id = ?", thread.UserID).+ Where("id = ?", thread.ID).+ UpdateColumn("is_read", false).+ Error+ })+ if err != nil {return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot save message thread with ID [%s]", thread.ID))}return nil}-// Update a new entities.MessageThread-func (repository *gormMessageThreadRepository) Update(ctx context.Context, thread *entities.MessageThread) error {+// UpdateActivity persists the last-message activity fields for a thread+func (repository *gormMessageThreadRepository) UpdateActivity(ctx context.Context, params MessageThreadActivityUpdate) error {ctx, span := repository.tracer.Start(ctx)defer span.End()- if err := repository.db.WithContext(ctx).Save(thread).Error; err != nil {- return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot update message thread thread with ID [%s]", thread.ID))+ result := repository.db.WithContext(ctx).+ Model(&entities.MessageThread{}).+ Where("user_id = ?", params.UserID).+ Where("id = ?", params.MessageThreadID).+ Updates(messageThreadActivityUpdates(params))+ if result.Error != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(result.Error, "cannot update message activity for thread [%s]", params.MessageThreadID))+ }+ if result.RowsAffected == 0 {+ return repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, ErrCodeNotFound, "thread with id [%s] not found", params.MessageThreadID))}return nil}+// UpdateStatus persists archive/read status fields for a thread+func (repository *gormMessageThreadRepository) UpdateStatus(+ ctx context.Context,+ userID entities.UserID,+ messageThreadID uuid.UUID,+ params MessageThreadStatusUpdate,+) (*entities.MessageThread, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ thread := new(entities.MessageThread)+ result := repository.db.WithContext(ctx).+ Model(thread).+ Clauses(clause.Returning{}).+ Where("user_id = ?", userID).+ Where("id = ?", messageThreadID).+ Updates(messageThreadStatusUpdates(params))+ if result.Error != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(result.Error, "cannot update status for thread [%s] and user [%s]", messageThreadID, userID))+ }+ if result.RowsAffected == 0 {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, ErrCodeNotFound, "thread with id [%s] not found for user with ID [%s]", messageThreadID, userID))+ }++ return thread, nil+}+// LoadByOwnerContact a thread between 2 usersfunc (repository *gormMessageThreadRepository) LoadByOwnerContact(ctx context.Context, userID entities.UserID, owner string, contact string) (*entities.MessageThread, error) {ctx, span := repository.tracer.Start(ctx)diff --git a/api/pkg/repositories/gorm_message_thread_repository_test.go b/api/pkg/repositories/gorm_message_thread_repository_test.gonew file mode 100644index 00000000..31dc43ed--- /dev/null+++ b/api/pkg/repositories/gorm_message_thread_repository_test.go@@ -0,0 +1,204 @@+package repositories++import (+ "context"+ "database/sql"+ "database/sql/driver"+ "errors"+ "strings"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "go.opentelemetry.io/otel/trace"+ "gorm.io/driver/postgres"+ "gorm.io/gorm"+)++type messageThreadTestStatement struct {+ query string+ args []any+}++type messageThreadTestConnPool struct {+ statements []messageThreadTestStatement+}++func (messageThreadTestConnPool) PrepareContext(context.Context, string) (*sql.Stmt, error) {+ return nil, errors.New("unexpected PrepareContext")+}++func (pool *messageThreadTestConnPool) ExecContext(_ context.Context, query string, args ...any) (sql.Result, error) {+ pool.statements = append(pool.statements, messageThreadTestStatement{+ query: query,+ args: append([]any(nil), args...),+ })+ return driver.RowsAffected(1), nil+}++func (messageThreadTestConnPool) QueryContext(context.Context, string, ...any) (*sql.Rows, error) {+ return nil, errors.New("unexpected QueryContext")+}++func (messageThreadTestConnPool) QueryRowContext(context.Context, string, ...any) *sql.Row {+ return &sql.Row{}+}++func (pool *messageThreadTestConnPool) BeginTx(context.Context, *sql.TxOptions) (gorm.ConnPool, error) {+ return pool, nil+}++func (*messageThreadTestConnPool) Commit() error {+ return nil+}++func (*messageThreadTestConnPool) Rollback() error {+ return nil+}++type messageThreadTestLogger struct{}++func (logger *messageThreadTestLogger) Error(error) {}+func (logger *messageThreadTestLogger) WithService(string) telemetry.Logger { return logger }++func (logger *messageThreadTestLogger) WithString(string, string) telemetry.Logger { return logger }++func (logger *messageThreadTestLogger) WithSpan(trace.SpanContext) telemetry.Logger { return logger }+func (logger *messageThreadTestLogger) Trace(string) {}+func (logger *messageThreadTestLogger) Info(string) {}+func (logger *messageThreadTestLogger) Warn(error) {}+func (logger *messageThreadTestLogger) Debug(string) {}+func (logger *messageThreadTestLogger) Fatal(error) {}+func (logger *messageThreadTestLogger) Printf(string, ...interface{}) {}++func TestMessageThreadStorePreservesExplicitUnreadState(t *testing.T) {+ pool := &messageThreadTestConnPool{}+ db, err := gorm.Open(+ postgres.New(postgres.Config{+ Conn: pool,+ WithoutReturning: true,+ }),+ &gorm.Config{DisableAutomaticPing: true},+ )+ require.NoError(t, err)++ logger := &messageThreadTestLogger{}+ repository := NewGormMessageThreadRepository(logger, telemetry.NewOtelLogger("test", logger), db)+ thread := &entities.MessageThread{+ ID: uuid.New(),+ IsRead: false,+ }++ require.NoError(t, repository.Store(context.Background(), thread))+ assert.False(t, thread.IsRead)++ require.NotEmpty(t, pool.statements)+ update := pool.statements[len(pool.statements)-1]+ assert.True(t, strings.HasPrefix(update.query, `UPDATE "message_threads"`))+ assert.Contains(t, update.query, `"is_read"=$1`)+ assert.Contains(t, update.args, false)+}++func TestMessageThreadActivityUpdatesOwnOnlyMessageColumns(t *testing.T) {+ messageID := uuid.New()+ updates := messageThreadActivityUpdates(MessageThreadActivityUpdate{+ Timestamp: time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC),+ MessageID: messageID,+ Content: "hello",+ Status: entities.MessageStatusReceived,+ })++ assert.Equal(t, map[string]any{+ "order_timestamp": time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC),+ "last_message_id": messageID,+ "last_message_content": "hello",+ "status": entities.MessageStatus(entities.MessageStatusReceived),+ }, updates)+ assert.NotContains(t, updates, "is_read")+ assert.NotContains(t, updates, "is_archived")+ assert.NotContains(t, updates, "last_read_at")+}++func TestUpdateActivityMarksUnreadWithOneQuery(t *testing.T) {+ pool := &messageThreadTestConnPool{}+ db, err := gorm.Open(+ postgres.New(postgres.Config{+ Conn: pool,+ WithoutReturning: true,+ }),+ &gorm.Config{DisableAutomaticPing: true},+ )+ require.NoError(t, err)++ logger := &messageThreadTestLogger{}+ repository := NewGormMessageThreadRepository(logger, telemetry.NewOtelLogger("test", logger), db)++ err = repository.UpdateActivity(context.Background(), MessageThreadActivityUpdate{+ MessageThreadID: uuid.New(),+ UserID: entities.UserID("user-id"),+ Timestamp: time.Date(2026, 7, 19, 10, 0, 0, 0, time.UTC),+ MessageID: uuid.New(),+ Content: "hello",+ Status: entities.MessageStatusReceived,+ MarkAsUnread: true,+ EventTimestamp: time.Date(2026, 7, 19, 10, 0, 1, 0, time.UTC),+ })++ require.NoError(t, err)+ var updates []messageThreadTestStatement+ for _, statement := range pool.statements {+ if strings.HasPrefix(statement.query, `UPDATE "message_threads"`) {+ updates = append(updates, statement)+ }+ }+ require.Len(t, updates, 1)+ assert.Contains(t, updates[0].query, `"is_read"=CASE WHEN last_read_at <`)+}++func TestMessageThreadDeletedUpdatesPreserveStatusType(t *testing.T) {+ messageID := uuid.New()+ content := "previous message"+ updates := messageThreadDeletedUpdates(MessageThreadDeletedUpdate{+ LastMessageID: &messageID,+ LastMessageContent: &content,+ LastMessageStatus: entities.MessageStatusDelivered,+ })++ assert.Equal(t, map[string]any{+ "last_message_id": &messageID,+ "last_message_content": &content,+ "status": entities.MessageStatus(entities.MessageStatusDelivered),+ }, updates)+}++func TestMessageThreadStatusUpdatesReadOnly(t *testing.T) {+ isRead := true+ readAt := time.Date(2026, 7, 18, 7, 1, 0, 0, time.UTC)++ updates := messageThreadStatusUpdates(MessageThreadStatusUpdate{+ IsRead: &isRead,+ ReadAt: readAt,+ })++ assert.Equal(t, map[string]any{+ "is_read": true,+ "last_read_at": readAt,+ }, updates)+ assert.NotContains(t, updates, "is_archived")+}++func TestMessageThreadStatusUpdatesArchiveOnly(t *testing.T) {+ isArchived := true++ updates := messageThreadStatusUpdates(MessageThreadStatusUpdate{+ IsArchived: &isArchived,+ })++ assert.Equal(t, map[string]any{"is_archived": true}, updates)+ assert.NotContains(t, updates, "is_read")+ assert.NotContains(t, updates, "last_read_at")+}diff --git a/api/pkg/repositories/message_thread_repository.go b/api/pkg/repositories/message_thread_repository.goindex 542fd519..e6093141 100644--- a/api/pkg/repositories/message_thread_repository.go+++ b/api/pkg/repositories/message_thread_repository.go@@ -2,19 +2,50 @@ package repositoriesimport ("context"+ "time""github.com/google/uuid""github.com/NdoleStudio/httpsms/pkg/entities")+type MessageThreadActivityUpdate struct {+ MessageThreadID uuid.UUID+ UserID entities.UserID+ // Timestamp controls thread activity ordering; EventTimestamp is the server-side unread watermark.+ Timestamp time.Time+ MessageID uuid.UUID+ Content string+ Status entities.MessageStatus+ MarkAsUnread bool+ EventTimestamp time.Time+ Unarchive bool+}++type MessageThreadStatusUpdate struct {+ IsArchived *bool+ IsRead *bool+ ReadAt time.Time+}++type MessageThreadDeletedUpdate struct {+ MessageThreadID uuid.UUID+ UserID entities.UserID+ LastMessageID *uuid.UUID+ LastMessageContent *string+ LastMessageStatus entities.MessageStatus+}+// MessageThreadRepository loads and persists an entities.MessageThreadtype MessageThreadRepository interface {// Store a new entities.MessageThreadStore(ctx context.Context, thread *entities.MessageThread) error- // Update a new entities.MessageThread- Update(ctx context.Context, thread *entities.MessageThread) error+ // UpdateActivity persists the last-message activity fields for a thread+ UpdateActivity(ctx context.Context, params MessageThreadActivityUpdate) error++ // UpdateStatus persists archive/read status fields for a thread+ UpdateStatus(ctx context.Context, userID entities.UserID, messageThreadID uuid.UUID, params MessageThreadStatusUpdate) (*entities.MessageThread, error)// LoadByOwnerContact fetches a thread between owner and contactLoadByOwnerContact(ctx context.Context, userID entities.UserID, owner string, contact string) (*entities.MessageThread, error)@@ -26,7 +57,7 @@ type MessageThreadRepository interface {Index(ctx context.Context, userID entities.UserID, owner string, archived bool, params IndexParams) (*[]entities.MessageThread, error)// UpdateAfterDeletedMessage updates a thread after the original message has been deleted- UpdateAfterDeletedMessage(ctx context.Context, userID entities.UserID, messageID uuid.UUID) error+ UpdateAfterDeletedMessage(ctx context.Context, params MessageThreadDeletedUpdate) error// Delete an entities.MessageThread by IDDelete(ctx context.Context, userID entities.UserID, messageThreadID uuid.UUID) errordiff --git a/api/pkg/requests/message_thread_update_request.go b/api/pkg/requests/message_thread_update_request.goindex d64d75c5..3309fc91 100644--- a/api/pkg/requests/message_thread_update_request.go+++ b/api/pkg/requests/message_thread_update_request.go@@ -10,7 +10,8 @@ import (// MessageThreadUpdate is the payload for updating a message threadtype MessageThreadUpdate struct {request- IsArchived bool `json:"is_archived" example:"true"`+ IsArchived *bool `json:"is_archived,omitempty" example:"true"`+ IsRead *bool `json:"is_read,omitempty" example:"true"`MessageThreadID string `json:"messageThreadID" swaggerignore:"true"` // used internally for validation}@@ -21,5 +22,6 @@ func (input *MessageThreadUpdate) ToUpdateParams(userID entities.UserID) serviceUserID: userID,MessageThreadID: uuid.MustParse(input.MessageThreadID),IsArchived: input.IsArchived,+ IsRead: input.IsRead,}}diff --git a/api/pkg/requests/message_thread_update_request_test.go b/api/pkg/requests/message_thread_update_request_test.gonew file mode 100644index 00000000..9f9579fd--- /dev/null+++ b/api/pkg/requests/message_thread_update_request_test.go@@ -0,0 +1,25 @@+package requests++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+)++func TestMessageThreadUpdateToUpdateParamsPreservesOptionalFields(t *testing.T) {+ threadID := uuid.New()+ isRead := true+ input := MessageThreadUpdate{+ MessageThreadID: threadID.String(),+ IsRead: &isRead,+ }++ params := input.ToUpdateParams(entities.UserID("user-id"))++ assert.Equal(t, threadID, params.MessageThreadID)+ assert.Equal(t, entities.UserID("user-id"), params.UserID)+ assert.Nil(t, params.IsArchived)+ assert.Same(t, &isRead, params.IsRead)+}diff --git a/api/pkg/responses/message_thead_responses.go b/api/pkg/responses/message_thead_responses.goindex 917706a4..e47fec28 100644--- a/api/pkg/responses/message_thead_responses.go+++ b/api/pkg/responses/message_thead_responses.go@@ -7,3 +7,9 @@ type MessageThreadsResponse struct {responseData []entities.MessageThread `json:"data"`}++// MessageThreadResponse is the payload containing entities.MessageThread+type MessageThreadResponse struct {+ response+ Data entities.MessageThread `json:"data"`+}diff --git a/api/pkg/services/message_thread_service.go b/api/pkg/services/message_thread_service.goindex c77458cb..e3dc882c 100644--- a/api/pkg/services/message_thread_service.go+++ b/api/pkg/services/message_thread_service.go@@ -50,7 +50,10 @@ type MessageThreadUpdateParams struct {Content stringUserID entities.UserIDMessageID uuid.UUID- Timestamp time.Time+ // Timestamp controls thread activity ordering; EventTimestamp is the server-side unread watermark.+ Timestamp time.Time+ MarkAsUnread bool+ EventTimestamp time.Time}// shouldCheckUnarchive reports whether a thread update is a new inbound message@@ -101,27 +104,39 @@ func (service *MessageThreadService) UpdateThread(ctx context.Context, params Mereturn nil}+ activity := repositories.MessageThreadActivityUpdate{+ MessageThreadID: thread.ID,+ UserID: params.UserID,+ Timestamp: params.Timestamp,+ MessageID: params.MessageID,+ Content: params.Content,+ Status: params.Status,+ MarkAsUnread: params.MarkAsUnread,+ EventTimestamp: params.EventTimestamp,+ }+if service.shouldCheckUnarchive(thread, params) {phone, phoneErr := service.phoneRepository.Load(ctx, params.UserID, params.Owner)if phoneErr != nil {ctxLogger.Warn(stacktrace.Propagate(phoneErr, "cannot load phone [%s] for user [%s] to resolve UnarchiveThread; leaving thread [%s] archived", params.Owner, params.UserID, thread.ID))} else if phone.UnarchiveThread {- thread.UpdateArchive(false)+ activity.Unarchive = truectxLogger.Info(fmt.Sprintf("unarchiving thread [%s] after inbound message [%s]", thread.ID, params.MessageID))}}- if err = service.repository.Update(ctx, thread.Update(params.Timestamp, params.MessageID, params.Content, params.Status)); err != nil {- return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot update message thread with id [%s] after adding message [%s]", thread.ID, params.MessageID))+ if err = service.repository.UpdateActivity(ctx, activity); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, stacktrace.GetCode(err), "cannot update message thread with id [%s] after adding message [%s]", thread.ID, params.MessageID))}- ctxLogger.Info(fmt.Sprintf("thread with id [%s] updated with last message [%s] and status [%s]", thread.ID, thread.LastMessageID, thread.Status))+ ctxLogger.Info(fmt.Sprintf("thread with id [%s] updated with last message [%s] and status [%s]", thread.ID, params.MessageID, params.Status))return nil}// MessageThreadStatusParams are parameters for updating a thread statustype MessageThreadStatusParams struct {- IsArchived bool+ IsArchived *bool+ IsRead *boolUserID entities.UserIDMessageThreadID uuid.UUID}@@ -131,18 +146,16 @@ func (service *MessageThreadService) UpdateStatus(ctx context.Context, params Mectx, span := service.tracer.Start(ctx)defer span.End()- ctxLogger := service.tracer.CtxLogger(service.logger, span)-- thread, err := service.repository.Load(ctx, params.UserID, params.MessageThreadID)- if err != nil {- return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot find thread with id [%s]", params.MessageThreadID))+ update := repositories.MessageThreadStatusUpdate{+ IsArchived: params.IsArchived,+ IsRead: params.IsRead,+ ReadAt: time.Now().UTC(),}-- if err = service.repository.Update(ctx, thread.UpdateArchive(params.IsArchived)); err != nil {- return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot update message thread with id [%s] with archive status [%t]", thread.ID, params.IsArchived))+ thread, err := service.repository.UpdateStatus(ctx, params.UserID, params.MessageThreadID, update)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, stacktrace.GetCode(err), "cannot update message thread with ID [%s] for user [%s]", params.MessageThreadID, params.UserID))}- ctxLogger.Info(fmt.Sprintf("thread with id [%s] updated with archive status [%t]", thread.ID, thread.IsArchived))return thread, nil}@@ -172,12 +185,13 @@ func (service *MessageThreadService) UpdateAfterDeletedMessage(ctx context.Contereturn nil}- thread.LastMessageContent = payload.PreviousMessageContent- thread.LastMessageID = payload.PreviousMessageID- thread.Status = *payload.PreviousMessageStatus- thread.UpdatedAt = time.Now().UTC()-- if err = service.repository.Update(ctx, thread); err != nil {+ if err = service.repository.UpdateAfterDeletedMessage(ctx, repositories.MessageThreadDeletedUpdate{+ MessageThreadID: thread.ID,+ UserID: thread.UserID,+ LastMessageID: payload.PreviousMessageID,+ LastMessageContent: payload.PreviousMessageContent,+ LastMessageStatus: *payload.PreviousMessageStatus,+ }); err != nil {return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, "cannot update thread with ID [%s] for user with ID [%s]", thread.ID, thread.UserID))}@@ -191,18 +205,21 @@ func (service *MessageThreadService) createThread(ctx context.Context, params MectxLogger := service.tracer.CtxLogger(service.logger, span)+ now := time.Now().UTC()thread := &entities.MessageThread{ID: uuid.New(),Owner: params.Owner,Contact: params.Contact,UserID: params.UserID,IsArchived: false,+ IsRead: !params.MarkAsUnread,+ LastReadAt: now,Color: service.getColor(),LastMessageContent: ¶ms.Content,Status: params.Status,LastMessageID: ¶ms.MessageID,- CreatedAt: time.Now().UTC(),- UpdatedAt: time.Now().UTC(),+ CreatedAt: now,+ UpdatedAt: now,OrderTimestamp: params.Timestamp,}diff --git a/api/pkg/services/message_thread_service_test.go b/api/pkg/services/message_thread_service_test.goindex 7e48ab43..fc1e8431 100644--- a/api/pkg/services/message_thread_service_test.go+++ b/api/pkg/services/message_thread_service_test.go@@ -1,12 +1,226 @@package servicesimport (+ "context""testing"+ "time""github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/google/uuid"+ "github.com/palantir/stacktrace""github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "gorm.io/gorm")+type messageThreadRepositoryStub struct {+ loadByOwnerContact func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error)+ load func(context.Context, entities.UserID, uuid.UUID) (*entities.MessageThread, error)+ store func(context.Context, *entities.MessageThread) error+ updateActivity func(context.Context, repositories.MessageThreadActivityUpdate) error+ updateStatus func(context.Context, entities.UserID, uuid.UUID, repositories.MessageThreadStatusUpdate) (*entities.MessageThread, error)+}++func (stub *messageThreadRepositoryStub) Store(ctx context.Context, thread *entities.MessageThread) error {+ if stub.store != nil {+ return stub.store(ctx, thread)+ }+ return nil+}++func (stub *messageThreadRepositoryStub) UpdateActivity(ctx context.Context, params repositories.MessageThreadActivityUpdate) error {+ if stub.updateActivity != nil {+ return stub.updateActivity(ctx, params)+ }+ return nil+}++func (stub *messageThreadRepositoryStub) UpdateStatus(ctx context.Context, userID entities.UserID, threadID uuid.UUID, params repositories.MessageThreadStatusUpdate) (*entities.MessageThread, error) {+ if stub.updateStatus != nil {+ return stub.updateStatus(ctx, userID, threadID, params)+ }+ return &entities.MessageThread{ID: threadID}, nil+}++func (stub *messageThreadRepositoryStub) UpdateAfterDeletedMessage(context.Context, repositories.MessageThreadDeletedUpdate) error {+ return nil+}++func (stub *messageThreadRepositoryStub) LoadByOwnerContact(ctx context.Context, userID entities.UserID, owner string, contact string) (*entities.MessageThread, error) {+ return stub.loadByOwnerContact(ctx, userID, owner, contact)+}++func (stub *messageThreadRepositoryStub) Load(ctx context.Context, userID entities.UserID, id uuid.UUID) (*entities.MessageThread, error) {+ return stub.load(ctx, userID, id)+}++func (stub *messageThreadRepositoryStub) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {+ threads := []entities.MessageThread{}+ return &threads, nil+}++func (stub *messageThreadRepositoryStub) Delete(context.Context, entities.UserID, uuid.UUID) error {+ return nil+}++func (stub *messageThreadRepositoryStub) DeleteAllForUser(context.Context, entities.UserID) error {+ return nil+}++func newMessageThreadServiceForTest(repository repositories.MessageThreadRepository) *MessageThreadService {+ logger := &noopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ return NewMessageThreadService(logger, tracer, repository, nil, nil)+}++func TestUpdateThreadPassesUnreadWatermarkForInboundActivity(t *testing.T) {+ threadID := uuid.New()+ eventTimestamp := time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC)+ var captured repositories.MessageThreadActivityUpdate+ repository := &messageThreadRepositoryStub{+ loadByOwnerContact: func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: threadID}, nil+ },+ updateActivity: func(_ context.Context, params repositories.MessageThreadActivityUpdate) error {+ captured = params+ return nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ err := service.UpdateThread(context.Background(), MessageThreadUpdateParams{+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ MessageID: uuid.New(),+ Content: "hello",+ Status: entities.MessageStatusReceived,+ Timestamp: eventTimestamp,+ MarkAsUnread: true,+ EventTimestamp: eventTimestamp,+ })++ require.NoError(t, err)+ assert.True(t, captured.MarkAsUnread)+ assert.Equal(t, eventTimestamp, captured.EventTimestamp)+}++func TestUpdateThreadPreservesReadStateForOutboundActivity(t *testing.T) {+ var captured repositories.MessageThreadActivityUpdate+ repository := &messageThreadRepositoryStub{+ loadByOwnerContact: func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: uuid.New(), IsRead: false}, nil+ },+ updateActivity: func(_ context.Context, params repositories.MessageThreadActivityUpdate) error {+ captured = params+ return nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ err := service.UpdateThread(context.Background(), MessageThreadUpdateParams{+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ MessageID: uuid.New(),+ Content: "outbound",+ Status: entities.MessageStatusSent,+ Timestamp: time.Now().UTC(),+ })++ require.NoError(t, err)+ assert.False(t, captured.MarkAsUnread)+}++func TestCreateThreadSetsReadStateFromActivityDirection(t *testing.T) {+ tests := []struct {+ name string+ marksUnread bool+ wantRead bool+ }{+ {name: "inbound", marksUnread: true, wantRead: false},+ {name: "outbound", marksUnread: false, wantRead: true},+ }++ for _, test := range tests {+ t.Run(test.name, func(t *testing.T) {+ var stored *entities.MessageThread+ repository := &messageThreadRepositoryStub{+ loadByOwnerContact: func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return nil, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found")+ },+ store: func(_ context.Context, thread *entities.MessageThread) error {+ stored = thread+ return nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ err := service.UpdateThread(context.Background(), MessageThreadUpdateParams{+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ MessageID: uuid.New(),+ Content: "hello",+ Status: entities.MessageStatusReceived,+ Timestamp: time.Now().UTC(),+ MarkAsUnread: test.marksUnread,+ })++ require.NoError(t, err)+ require.NotNil(t, stored)+ assert.Equal(t, test.wantRead, stored.IsRead)+ assert.False(t, stored.LastReadAt.IsZero())+ })+ }+}++func TestUpdateStatusChangesOnlyRequestedState(t *testing.T) {+ threadID := uuid.New()+ isRead := false+ var captured repositories.MessageThreadStatusUpdate+ repository := &messageThreadRepositoryStub{+ updateStatus: func(_ context.Context, _ entities.UserID, _ uuid.UUID, params repositories.MessageThreadStatusUpdate) (*entities.MessageThread, error) {+ captured = params+ return &entities.MessageThread{ID: threadID, IsArchived: true, IsRead: false}, nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ thread, err := service.UpdateStatus(context.Background(), MessageThreadStatusParams{+ UserID: entities.UserID("user-id"),+ MessageThreadID: threadID,+ IsRead: &isRead,+ })++ require.NoError(t, err)+ assert.Nil(t, captured.IsArchived)+ assert.Same(t, &isRead, captured.IsRead)+ assert.False(t, captured.ReadAt.IsZero())+ assert.True(t, thread.IsArchived)+ assert.False(t, thread.IsRead)+}++func TestUpdateStatusPreservesNotFoundCode(t *testing.T) {+ repository := &messageThreadRepositoryStub{+ updateStatus: func(context.Context, entities.UserID, uuid.UUID, repositories.MessageThreadStatusUpdate) (*entities.MessageThread, error) {+ return nil, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found")+ },+ }++ service := newMessageThreadServiceForTest(repository)+ isRead := true+ _, err := service.UpdateStatus(context.Background(), MessageThreadStatusParams{+ UserID: entities.UserID("user-id"),+ MessageThreadID: uuid.New(),+ IsRead: &isRead,+ })++ assert.Equal(t, repositories.ErrCodeNotFound, stacktrace.GetCode(err))+}+func TestShouldCheckUnarchive(t *testing.T) {service := &MessageThreadService{}diff --git a/api/pkg/validators/message_thread_handler_validator.go b/api/pkg/validators/message_thread_handler_validator.goindex a4e5cd64..72a64194 100644--- a/api/pkg/validators/message_thread_handler_validator.go+++ b/api/pkg/validators/message_thread_handler_validator.go@@ -72,5 +72,13 @@ func (validator *MessageThreadHandlerValidator) ValidateUpdate(_ context.Context},})- return v.ValidateStruct()+ errors := v.ValidateStruct()+ if request.IsArchived == nil && request.IsRead == nil {+ if errors == nil {+ errors = url.Values{}+ }+ errors.Add("payload", "at least one of is_archived or is_read is required")+ }++ return errors}diff --git a/api/pkg/validators/message_thread_handler_validator_test.go b/api/pkg/validators/message_thread_handler_validator_test.gonew file mode 100644index 00000000..e5ec7c1b--- /dev/null+++ b/api/pkg/validators/message_thread_handler_validator_test.go@@ -0,0 +1,34 @@+package validators++import (+ "context"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+)++func TestValidateUpdateRequiresAtLeastOneStatusField(t *testing.T) {+ validator := &MessageThreadHandlerValidator{}+ request := requests.MessageThreadUpdate{+ MessageThreadID: uuid.NewString(),+ }++ errors := validator.ValidateUpdate(context.Background(), request)++ assert.NotEmpty(t, errors.Get("payload"))+}++func TestValidateUpdateAcceptsReadOnlyUpdate(t *testing.T) {+ validator := &MessageThreadHandlerValidator{}+ isRead := true+ request := requests.MessageThreadUpdate{+ MessageThreadID: uuid.NewString(),+ IsRead: &isRead,+ }++ errors := validator.ValidateUpdate(context.Background(), request)++ assert.Empty(t, errors)+}diff --git a/docs/superpowers/plans/2026-07-18-read-receipts.md b/docs/superpowers/plans/2026-07-18-read-receipts.mdnew file mode 100644index 00000000..1887a151--- /dev/null+++ b/docs/superpowers/plans/2026-07-18-read-receipts.md@@ -0,0 +1,1760 @@+# Message Thread Read Receipts 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:** Persist message-thread read state, mark inbound SMS and missed calls unread, automatically mark opened threads read, and highlight unread threads in the web UI.++**Architecture:** Store `is_read` plus an internal `last_read_at` watermark on each message thread. Replace full-row thread saves with field-scoped GORM updates so concurrent event listeners cannot overwrite a newer read action; inbound updates compare CloudEvent creation time against the stored watermark. Extend the existing thread update endpoint with optional archive/read fields, then have the Nuxt store call it automatically when the thread page opens or refreshes after inbound realtime events.++**Tech Stack:** Go 1.25, Fiber v3, GORM/PostgreSQL, CloudEvents, Pusher, Nuxt 4 SPA, Vue 3, Pinia, Vuetify 4, TypeScript.++## Global Constraints++- Work only in `C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts` on branch `feat/read-receipts`, based on `origin/main`.+- Existing message threads must migrate as read.+- Only incoming SMS and missed-call activity marks a thread unread.+- Outbound messages and delivery/status events preserve the existing read state.+- Opening a thread marks it read automatically; inbound activity while it is open must leave it read.+- Do not add a new endpoint or a manual read/unread control.+- Use the existing `PUT /v1/message-threads/{messageThreadID}` endpoint with optional `is_archived` and `is_read`.+- Use GORM query builders with `WithContext(ctx)`; do not use raw SQL.+- Wrap API errors with `stacktrace.Propagate`/`PropagateWithCode`.+- Web code uses single quotes, no semicolons, and 2-space indentation.+- Every commit must end with:++```text+Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+```++- Add end-to-end coverage in the existing `tests/` integration project.++## File Structure++- `api/pkg/entities/message_thread.go`: persisted read fields.+- `api/pkg/entities/message_thread_test.go`: schema-default regression tests.+- `api/pkg/repositories/message_thread_repository.go`: field-scoped update parameter types and interface methods.+- `api/pkg/repositories/gorm_message_thread_repository.go`: transactional activity updates, conditional unread transition, partial user-status update, and partial deleted-message update.+- `api/pkg/repositories/gorm_message_thread_repository_test.go`: update-map ownership tests.+- `api/pkg/services/message_thread_service.go`: read-state business rules and repository orchestration.+- `api/pkg/services/message_thread_service_test.go`: service behavior with a repository stub.+- `api/pkg/requests/message_thread_update_request.go`: optional archive/read request fields.+- `api/pkg/requests/message_thread_update_request_test.go`: request-to-service conversion tests.+- `api/pkg/validators/message_thread_handler_validator.go`: require at least one update field.+- `api/pkg/validators/message_thread_handler_validator_test.go`: empty-payload and valid-payload tests.+- `api/pkg/responses/message_thead_responses.go`: single-thread Swagger response.+- `api/pkg/handlers/message_thread_handler.go`: not-found mapping and corrected Swagger response.+- `api/pkg/listeners/message_thread_listener.go`: incoming SMS and missed-call unread updates.+- `api/pkg/listeners/websocket_listener.go`: missed-call Pusher publication.+- `api/pkg/listeners/read_receipts_test_helpers_test.go`: listener logger and repository test doubles.+- `api/pkg/listeners/message_thread_listener_test.go`: listener route and payload tests.+- `api/pkg/listeners/websocket_listener_test.go`: missed-call route registration test.+- `api/docs/docs.go`, `api/docs/swagger.json`, `api/docs/swagger.yaml`: regenerated API documentation.+- `web/shared/types/api.ts`: regenerated thread/request types.+- `web/app/stores/threads.ts`: automatic read update and local state replacement.+- `web/app/pages/threads/[id]/index.vue`: non-blocking read calls and missed-call realtime refresh.+- `web/app/components/MessageThread.vue`: unread visual treatment.+- `tests/read_receipts_test.go`: Docker-stack read/unread lifecycle coverage.+- `tests/README.md`: integration coverage documentation.++---++### Task 1: Add the read-state API contract++**Files:**++- Modify: `api/pkg/entities/message_thread.go`+- Create: `api/pkg/entities/message_thread_test.go`+- Modify: `api/pkg/requests/message_thread_update_request.go`+- Create: `api/pkg/requests/message_thread_update_request_test.go`+- Modify: `api/pkg/validators/message_thread_handler_validator.go`+- Create: `api/pkg/validators/message_thread_handler_validator_test.go`+- Modify: `api/pkg/responses/message_thead_responses.go`+- Modify: `api/pkg/services/message_thread_service.go`++**Interfaces:**++- Produces: `MessageThread.IsRead bool`, `MessageThread.LastReadAt time.Time`+- Produces: `MessageThreadUpdate.IsArchived *bool`, `MessageThreadUpdate.IsRead *bool`+- Produces: `MessageThreadStatusParams.IsArchived *bool`, `MessageThreadStatusParams.IsRead *bool`+- Produces: `responses.MessageThreadResponse`++- [ ] **Step 1: Write failing entity schema tests**++Create `api/pkg/entities/message_thread_test.go`:++```go+package entities++import (+ "reflect"+ "testing"++ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestMessageThreadReadFieldsHaveBackwardCompatibleDefaults(t *testing.T) {+ threadType := reflect.TypeOf(MessageThread{})++ isRead, ok := threadType.FieldByName("IsRead")+ require.True(t, ok)+ assert.Contains(t, isRead.Tag.Get("gorm"), "not null")+ assert.Contains(t, isRead.Tag.Get("gorm"), "default:true")+ assert.Equal(t, "is_read", isRead.Tag.Get("json"))++ lastReadAt, ok := threadType.FieldByName("LastReadAt")+ require.True(t, ok)+ assert.Contains(t, lastReadAt.Tag.Get("gorm"), "not null")+ assert.Contains(t, lastReadAt.Tag.Get("gorm"), "default:CURRENT_TIMESTAMP")+ assert.Equal(t, "-", lastReadAt.Tag.Get("json"))+}+```++- [ ] **Step 2: Write failing request and validator tests**++Create `api/pkg/requests/message_thread_update_request_test.go`:++```go+package requests++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+)++func TestMessageThreadUpdateToUpdateParamsPreservesOptionalFields(t *testing.T) {+ threadID := uuid.New()+ isRead := true+ input := MessageThreadUpdate{+ MessageThreadID: threadID.String(),+ IsRead: &isRead,+ }++ params := input.ToUpdateParams(entities.UserID("user-id"))++ assert.Equal(t, threadID, params.MessageThreadID)+ assert.Equal(t, entities.UserID("user-id"), params.UserID)+ assert.Nil(t, params.IsArchived)+ assert.Same(t, &isRead, params.IsRead)+}+```++Create `api/pkg/validators/message_thread_handler_validator_test.go`:++```go+package validators++import (+ "context"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+)++func TestValidateUpdateRequiresAtLeastOneStatusField(t *testing.T) {+ validator := &MessageThreadHandlerValidator{}+ request := requests.MessageThreadUpdate{+ MessageThreadID: uuid.NewString(),+ }++ errors := validator.ValidateUpdate(context.Background(), request)++ assert.NotEmpty(t, errors.Get("payload"))+}++func TestValidateUpdateAcceptsReadOnlyUpdate(t *testing.T) {+ validator := &MessageThreadHandlerValidator{}+ isRead := true+ request := requests.MessageThreadUpdate{+ MessageThreadID: uuid.NewString(),+ IsRead: &isRead,+ }++ errors := validator.ValidateUpdate(context.Background(), request)++ assert.Empty(t, errors)+}+```++- [ ] **Step 3: Run the focused tests and confirm they fail**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\api'+go test ./pkg/entities ./pkg/requests ./pkg/validators+```++Expected: compile failures because the read fields and optional request fields do not exist.++- [ ] **Step 4: Add the persisted fields and optional request contract**++Add to `entities.MessageThread` after `IsArchived`:++```go+IsRead bool `json:"is_read" gorm:"not null;default:true" example:"true"`+LastReadAt time.Time `json:"-" gorm:"not null;default:CURRENT_TIMESTAMP"`+```++Change `requests.MessageThreadUpdate` and its conversion:++```go+type MessageThreadUpdate struct {+ request+ IsArchived *bool `json:"is_archived,omitempty" example:"true"`+ IsRead *bool `json:"is_read,omitempty" example:"true"`++ MessageThreadID string `json:"messageThreadID" swaggerignore:"true"`+}++func (input *MessageThreadUpdate) ToUpdateParams(userID entities.UserID) services.MessageThreadStatusParams {+ return services.MessageThreadStatusParams{+ UserID: userID,+ MessageThreadID: uuid.MustParse(input.MessageThreadID),+ IsArchived: input.IsArchived,+ IsRead: input.IsRead,+ }+}+```++Change the service parameter type:++```go+type MessageThreadStatusParams struct {+ IsArchived *bool+ IsRead *bool+ UserID entities.UserID+ MessageThreadID uuid.UUID+}+```++After `v.ValidateStruct()` in `ValidateUpdate`, add an explicit payload check:++```go+errors := v.ValidateStruct()+if request.IsArchived == nil && request.IsRead == nil {+ errors.Add("payload", "at least one of is_archived or is_read is required")+}+return errors+```++Add a single-thread response beside `MessageThreadsResponse`:++```go+// MessageThreadResponse is the payload containing entities.MessageThread+type MessageThreadResponse struct {+ response+ Data entities.MessageThread `json:"data"`+}+```++- [ ] **Step 5: Run focused tests**++Run:++```powershell+go test ./pkg/entities ./pkg/requests ./pkg/validators+```++Expected: PASS.++- [ ] **Step 6: Commit the contract**++```powershell+git add api/pkg/entities/message_thread.go api/pkg/entities/message_thread_test.go api/pkg/requests/message_thread_update_request.go api/pkg/requests/message_thread_update_request_test.go api/pkg/validators/message_thread_handler_validator.go api/pkg/validators/message_thread_handler_validator_test.go api/pkg/responses/message_thead_responses.go api/pkg/services/message_thread_service.go+@'+feat(api): add thread read state contract++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 2: Add atomic thread persistence operations++**Files:**++- Modify: `api/pkg/repositories/message_thread_repository.go`+- Modify: `api/pkg/repositories/gorm_message_thread_repository.go`+- Create: `api/pkg/repositories/gorm_message_thread_repository_test.go`++**Interfaces:**++- Produces: `repositories.MessageThreadActivityUpdate`+- Produces: `repositories.MessageThreadStatusUpdate`+- Produces: `repositories.MessageThreadDeletedUpdate`+- Produces: `MessageThreadRepository.UpdateActivity`, `UpdateStatus`, `UpdateAfterDeletedMessage`+- Removes: `MessageThreadRepository.Update`++- [ ] **Step 1: Write failing update-map ownership tests**++Create `api/pkg/repositories/gorm_message_thread_repository_test.go`:++```go+package repositories++import (+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+)++func TestMessageThreadActivityUpdatesOwnOnlyMessageColumns(t *testing.T) {+ messageID := uuid.New()+ updates := messageThreadActivityUpdates(MessageThreadActivityUpdate{+ Timestamp: time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC),+ MessageID: messageID,+ Content: "hello",+ Status: entities.MessageStatusReceived,+ })++ assert.Equal(t, map[string]any{+ "order_timestamp": time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC),+ "last_message_id": messageID,+ "last_message_content": "hello",+ "status": entities.MessageStatusReceived,+ }, updates)+ assert.NotContains(t, updates, "is_read")+ assert.NotContains(t, updates, "is_archived")+ assert.NotContains(t, updates, "last_read_at")+}++func TestMessageThreadStatusUpdatesReadOnly(t *testing.T) {+ isRead := true+ readAt := time.Date(2026, 7, 18, 7, 1, 0, 0, time.UTC)++ updates := messageThreadStatusUpdates(MessageThreadStatusUpdate{+ IsRead: &isRead,+ ReadAt: readAt,+ })++ assert.Equal(t, map[string]any{+ "is_read": true,+ "last_read_at": readAt,+ }, updates)+ assert.NotContains(t, updates, "is_archived")+}++func TestMessageThreadStatusUpdatesArchiveOnly(t *testing.T) {+ isArchived := true++ updates := messageThreadStatusUpdates(MessageThreadStatusUpdate{+ IsArchived: &isArchived,+ })++ assert.Equal(t, map[string]any{"is_archived": true}, updates)+ assert.NotContains(t, updates, "is_read")+ assert.NotContains(t, updates, "last_read_at")+}+```++- [ ] **Step 2: Run the repository test and confirm it fails**++Run:++```powershell+go test ./pkg/repositories -run MessageThread -v+```++Expected: compile failures because the parameter types and helper functions do not exist.++- [ ] **Step 3: Define repository update parameters and methods**++In `message_thread_repository.go`, add:++```go+type MessageThreadActivityUpdate struct {+ MessageThreadID uuid.UUID+ UserID entities.UserID+ Timestamp time.Time+ MessageID uuid.UUID+ Content string+ Status entities.MessageStatus+ MarksUnread bool+ EventTimestamp time.Time+}++type MessageThreadStatusUpdate struct {+ IsArchived *bool+ IsRead *bool+ ReadAt time.Time+}++type MessageThreadDeletedUpdate struct {+ MessageThreadID uuid.UUID+ UserID entities.UserID+ LastMessageID *uuid.UUID+ LastMessageContent *string+ LastMessageStatus entities.MessageStatus+}+```++Add the `time` import. Replace `Update` and the old deleted-message method in the interface with:++```go+UpdateActivity(ctx context.Context, params MessageThreadActivityUpdate) error+UpdateStatus(ctx context.Context, userID entities.UserID, messageThreadID uuid.UUID, params MessageThreadStatusUpdate) error+UpdateAfterDeletedMessage(ctx context.Context, params MessageThreadDeletedUpdate) error+```++- [ ] **Step 4: Implement field-scoped GORM updates**++Add these helpers to `gorm_message_thread_repository.go`:++```go+func messageThreadActivityUpdates(params MessageThreadActivityUpdate) map[string]any {+ return map[string]any{+ "order_timestamp": params.Timestamp,+ "last_message_id": params.MessageID,+ "last_message_content": params.Content,+ "status": params.Status,+ }+}++func messageThreadStatusUpdates(params MessageThreadStatusUpdate) map[string]any {+ updates := make(map[string]any)+ if params.IsArchived != nil {+ updates["is_archived"] = *params.IsArchived+ }+ if params.IsRead != nil {+ updates["is_read"] = *params.IsRead+ if *params.IsRead {+ updates["last_read_at"] = params.ReadAt+ }+ }+ return updates+}+```++Replace the full-row `Update` implementation with:++```go+func (repository *gormMessageThreadRepository) UpdateActivity(ctx context.Context, params MessageThreadActivityUpdate) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ err := repository.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {+ query := tx.Model(&entities.MessageThread{}).+ Where("user_id = ?", params.UserID).+ Where("id = ?", params.MessageThreadID)++ result := query.Updates(messageThreadActivityUpdates(params))+ if result.Error != nil {+ return result.Error+ }+ if result.RowsAffected == 0 {+ return stacktrace.PropagateWithCode(+ gorm.ErrRecordNotFound,+ ErrCodeNotFound,+ fmt.Sprintf("thread with id [%s] not found", params.MessageThreadID),+ )+ }++ if !params.MarksUnread {+ return nil+ }++ return tx.Model(&entities.MessageThread{}).+ Where("user_id = ?", params.UserID).+ Where("id = ?", params.MessageThreadID).+ Where("last_read_at < ?", params.EventTimestamp).+ Update("is_read", false).+ Error+ })+ if err != nil {+ msg := fmt.Sprintf("cannot update message activity for thread [%s]", params.MessageThreadID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, stacktrace.GetCode(err), msg))+ }+ return nil+}++func (repository *gormMessageThreadRepository) UpdateStatus(+ ctx context.Context,+ userID entities.UserID,+ messageThreadID uuid.UUID,+ params MessageThreadStatusUpdate,+) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ result := repository.db.WithContext(ctx).+ Model(&entities.MessageThread{}).+ Where("user_id = ?", userID).+ Where("id = ?", messageThreadID).+ Updates(messageThreadStatusUpdates(params))+ if result.Error != nil {+ msg := fmt.Sprintf("cannot update status for thread [%s]", messageThreadID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(result.Error, msg))+ }+ if result.RowsAffected == 0 {+ msg := fmt.Sprintf("thread with id [%s] not found", messageThreadID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, ErrCodeNotFound, msg))+ }+ return nil+}++func (repository *gormMessageThreadRepository) UpdateAfterDeletedMessage(ctx context.Context, params MessageThreadDeletedUpdate) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ result := repository.db.WithContext(ctx).+ Model(&entities.MessageThread{}).+ Where("user_id = ?", params.UserID).+ Where("id = ?", params.MessageThreadID).+ Updates(map[string]any{+ "last_message_id": params.LastMessageID,+ "last_message_content": params.LastMessageContent,+ "status": params.LastMessageStatus,+ })+ if result.Error != nil {+ msg := fmt.Sprintf("cannot update deleted-message metadata for thread [%s]", params.MessageThreadID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(result.Error, msg))+ }+ return nil+}+```++Delete the old `Save(thread)` method and the old unused `UpdateAfterDeletedMessage(userID, messageID)` implementation.++- [ ] **Step 5: Run repository tests**++Run:++```powershell+go test ./pkg/repositories -run MessageThread -v+```++Expected: PASS.++- [ ] **Step 6: Commit atomic persistence**++```powershell+git add api/pkg/repositories/message_thread_repository.go api/pkg/repositories/gorm_message_thread_repository.go api/pkg/repositories/gorm_message_thread_repository_test.go+@'+refactor(api): make thread updates atomic++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 3: Apply read rules in services and listeners++**Files:**++- Modify: `api/pkg/services/message_thread_service.go`+- Create: `api/pkg/services/message_thread_service_test.go`+- Modify: `api/pkg/listeners/message_thread_listener.go`+- Create: `api/pkg/listeners/read_receipts_test_helpers_test.go`+- Create: `api/pkg/listeners/message_thread_listener_test.go`+- Modify: `api/pkg/listeners/websocket_listener.go`+- Create: `api/pkg/listeners/websocket_listener_test.go`++**Interfaces:**++- Consumes: repository update types and methods from Task 2.+- Produces: `MessageThreadUpdateParams.MarksUnread bool`+- Produces: `MessageThreadUpdateParams.EventTimestamp time.Time`+- Produces: missed-call thread and websocket listeners.++- [ ] **Step 1: Write failing service behavior tests**++Create `api/pkg/services/message_thread_service_test.go`. Implement a repository stub with all interface methods returning zero values by default and function hooks for the methods under test:++```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/google/uuid"+ "github.com/palantir/stacktrace"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "gorm.io/gorm"+)++type messageThreadRepositoryStub struct {+ loadByOwnerContact func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error)+ load func(context.Context, entities.UserID, uuid.UUID) (*entities.MessageThread, error)+ store func(context.Context, *entities.MessageThread) error+ updateActivity func(context.Context, repositories.MessageThreadActivityUpdate) error+ updateStatus func(context.Context, entities.UserID, uuid.UUID, repositories.MessageThreadStatusUpdate) error+}++func (stub *messageThreadRepositoryStub) Store(ctx context.Context, thread *entities.MessageThread) error {+ if stub.store != nil {+ return stub.store(ctx, thread)+ }+ return nil+}++func (stub *messageThreadRepositoryStub) UpdateActivity(ctx context.Context, params repositories.MessageThreadActivityUpdate) error {+ if stub.updateActivity != nil {+ return stub.updateActivity(ctx, params)+ }+ return nil+}++func (stub *messageThreadRepositoryStub) UpdateStatus(ctx context.Context, userID entities.UserID, threadID uuid.UUID, params repositories.MessageThreadStatusUpdate) error {+ if stub.updateStatus != nil {+ return stub.updateStatus(ctx, userID, threadID, params)+ }+ return nil+}++func (stub *messageThreadRepositoryStub) UpdateAfterDeletedMessage(context.Context, repositories.MessageThreadDeletedUpdate) error {+ return nil+}++func (stub *messageThreadRepositoryStub) LoadByOwnerContact(ctx context.Context, userID entities.UserID, owner string, contact string) (*entities.MessageThread, error) {+ return stub.loadByOwnerContact(ctx, userID, owner, contact)+}++func (stub *messageThreadRepositoryStub) Load(ctx context.Context, userID entities.UserID, id uuid.UUID) (*entities.MessageThread, error) {+ return stub.load(ctx, userID, id)+}++func (stub *messageThreadRepositoryStub) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {+ threads := []entities.MessageThread{}+ return &threads, nil+}++func (stub *messageThreadRepositoryStub) Delete(context.Context, entities.UserID, uuid.UUID) error {+ return nil+}++func (stub *messageThreadRepositoryStub) DeleteAllForUser(context.Context, entities.UserID) error {+ return nil+}++func newMessageThreadServiceForTest(repository repositories.MessageThreadRepository) *MessageThreadService {+ logger := &noopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ return NewMessageThreadService(logger, tracer, repository, nil)+}+```++Add these tests below the stub:++```go+func TestUpdateThreadPassesUnreadWatermarkForInboundActivity(t *testing.T) {+ threadID := uuid.New()+ eventTimestamp := time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC)+ var captured repositories.MessageThreadActivityUpdate+ repository := &messageThreadRepositoryStub{+ loadByOwnerContact: func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: threadID}, nil+ },+ updateActivity: func(_ context.Context, params repositories.MessageThreadActivityUpdate) error {+ captured = params+ return nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ err := service.UpdateThread(context.Background(), MessageThreadUpdateParams{+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ MessageID: uuid.New(),+ Content: "hello",+ Status: entities.MessageStatusReceived,+ Timestamp: eventTimestamp,+ MarksUnread: true,+ EventTimestamp: eventTimestamp,+ })++ require.NoError(t, err)+ assert.True(t, captured.MarksUnread)+ assert.Equal(t, eventTimestamp, captured.EventTimestamp)+}++func TestUpdateThreadPreservesReadStateForOutboundActivity(t *testing.T) {+ var captured repositories.MessageThreadActivityUpdate+ repository := &messageThreadRepositoryStub{+ loadByOwnerContact: func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: uuid.New(), IsRead: false}, nil+ },+ updateActivity: func(_ context.Context, params repositories.MessageThreadActivityUpdate) error {+ captured = params+ return nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ err := service.UpdateThread(context.Background(), MessageThreadUpdateParams{+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ MessageID: uuid.New(),+ Content: "outbound",+ Status: entities.MessageStatusSent,+ Timestamp: time.Now().UTC(),+ })++ require.NoError(t, err)+ assert.False(t, captured.MarksUnread)+}++func TestCreateThreadSetsReadStateFromActivityDirection(t *testing.T) {+ tests := []struct {+ name string+ marksUnread bool+ wantRead bool+ }{+ {name: "inbound", marksUnread: true, wantRead: false},+ {name: "outbound", marksUnread: false, wantRead: true},+ }++ for _, test := range tests {+ t.Run(test.name, func(t *testing.T) {+ var stored *entities.MessageThread+ repository := &messageThreadRepositoryStub{+ loadByOwnerContact: func(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return nil, stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found")+ },+ store: func(_ context.Context, thread *entities.MessageThread) error {+ stored = thread+ return nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ err := service.UpdateThread(context.Background(), MessageThreadUpdateParams{+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ MessageID: uuid.New(),+ Content: "hello",+ Status: entities.MessageStatusReceived,+ Timestamp: time.Now().UTC(),+ MarksUnread: test.marksUnread,+ })++ require.NoError(t, err)+ require.NotNil(t, stored)+ assert.Equal(t, test.wantRead, stored.IsRead)+ assert.False(t, stored.LastReadAt.IsZero())+ })+ }+}++func TestUpdateStatusChangesOnlyRequestedState(t *testing.T) {+ threadID := uuid.New()+ isRead := true+ var captured repositories.MessageThreadStatusUpdate+ repository := &messageThreadRepositoryStub{+ updateStatus: func(_ context.Context, _ entities.UserID, _ uuid.UUID, params repositories.MessageThreadStatusUpdate) error {+ captured = params+ return nil+ },+ load: func(context.Context, entities.UserID, uuid.UUID) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: threadID, IsArchived: true, IsRead: true}, nil+ },+ }++ service := newMessageThreadServiceForTest(repository)+ thread, err := service.UpdateStatus(context.Background(), MessageThreadStatusParams{+ UserID: entities.UserID("user-id"),+ MessageThreadID: threadID,+ IsRead: &isRead,+ })++ require.NoError(t, err)+ assert.Nil(t, captured.IsArchived)+ assert.Same(t, &isRead, captured.IsRead)+ assert.False(t, captured.ReadAt.IsZero())+ assert.True(t, thread.IsArchived)+}++func TestUpdateStatusPreservesNotFoundCode(t *testing.T) {+ repository := &messageThreadRepositoryStub{+ updateStatus: func(context.Context, entities.UserID, uuid.UUID, repositories.MessageThreadStatusUpdate) error {+ return stacktrace.PropagateWithCode(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found")+ },+ }++ service := newMessageThreadServiceForTest(repository)+ isRead := true+ _, err := service.UpdateStatus(context.Background(), MessageThreadStatusParams{+ UserID: entities.UserID("user-id"),+ MessageThreadID: uuid.New(),+ IsRead: &isRead,+ })++ assert.Equal(t, repositories.ErrCodeNotFound, stacktrace.GetCode(err))+}+```++- [ ] **Step 2: Run service tests and confirm they fail**++Run:++```powershell+go test ./pkg/services -run 'Test(UpdateThread|CreateThread|UpdateStatus)' -v+```++Expected: compile failures because the new update parameters and repository calls are not wired.++- [ ] **Step 3: Implement service read rules**++Extend `MessageThreadUpdateParams`:++```go+MarksUnread bool+EventTimestamp time.Time+```++Replace the existing full-row update in `UpdateThread` with:++```go+if err = service.repository.UpdateActivity(ctx, repositories.MessageThreadActivityUpdate{+ MessageThreadID: thread.ID,+ UserID: params.UserID,+ Timestamp: params.Timestamp,+ MessageID: params.MessageID,+ Content: params.Content,+ Status: params.Status,+ MarksUnread: params.MarksUnread,+ EventTimestamp: params.EventTimestamp,+}); err != nil {+ msg := fmt.Sprintf("cannot update message thread with id [%s] after adding message [%s]", thread.ID, params.MessageID)+ return service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, stacktrace.GetCode(err), msg))+}+```++In `createThread`, create one `now := time.Now().UTC()` and initialize:++```go+IsRead: !params.MarksUnread,+LastReadAt: now,+CreatedAt: now,+UpdatedAt: now,+```++Replace `UpdateStatus` with a partial repository update followed by a reload:++```go+func (service *MessageThreadService) UpdateStatus(ctx context.Context, params MessageThreadStatusParams) (*entities.MessageThread, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ update := repositories.MessageThreadStatusUpdate{+ IsArchived: params.IsArchived,+ IsRead: params.IsRead,+ ReadAt: time.Now().UTC(),+ }+ if err := service.repository.UpdateStatus(ctx, params.UserID, params.MessageThreadID, update); err != nil {+ msg := fmt.Sprintf("cannot update message thread with id [%s]", params.MessageThreadID)+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, stacktrace.GetCode(err), msg))+ }++ thread, err := service.repository.Load(ctx, params.UserID, params.MessageThreadID)+ if err != nil {+ msg := fmt.Sprintf("cannot reload message thread with id [%s]", params.MessageThreadID)+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, stacktrace.GetCode(err), msg))+ }+ return thread, nil+}+```++In `UpdateAfterDeletedMessage`, replace the full-row update with:++```go+if err = service.repository.UpdateAfterDeletedMessage(ctx, repositories.MessageThreadDeletedUpdate{+ MessageThreadID: thread.ID,+ UserID: thread.UserID,+ LastMessageID: payload.PreviousMessageID,+ LastMessageContent: payload.PreviousMessageContent,+ LastMessageStatus: *payload.PreviousMessageStatus,+}); err != nil {+ msg := fmt.Sprintf("cannot update thread with ID [%s] for user with ID [%s]", thread.ID, thread.UserID)+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+}+```++- [ ] **Step 4: Add inbound and missed-call listener behavior**++In `NewMessageThreadListener`, register:++```go+events.MessageCallMissed: l.OnMessageCallMissed,+```++In `OnMessagePhoneReceived`, add:++```go+MarksUnread: true,+EventTimestamp: event.Time(),+```++Add:++```go+func (listener *MessageThreadListener) OnMessageCallMissed(ctx context.Context, event cloudevents.Event) error {+ ctx, span := listener.tracer.Start(ctx)+ defer span.End()++ var payload events.MessageCallMissedPayload+ if err := event.DataAs(&payload); err != nil {+ msg := fmt.Sprintf("cannot decode [%s] into [%T]", event.Data(), payload)+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ params := services.MessageThreadUpdateParams{+ Owner: payload.Owner,+ Contact: payload.Contact,+ UserID: payload.UserID,+ Status: entities.MessageStatusReceived,+ Timestamp: payload.Timestamp,+ Content: "Missed phone call",+ MessageID: payload.MessageID,+ MarksUnread: true,+ EventTimestamp: event.Time(),+ }+ if err := listener.service.UpdateThread(ctx, params); err != nil {+ msg := fmt.Sprintf("cannot update thread for missed call [%s] on event [%s]", payload.MessageID, event.ID())+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }+ return nil+}+```++In `NewWebsocketListener`, register:++```go+events.MessageCallMissed: l.onMessageCallMissed,+```++Add:++```go+func (listener *WebsocketListener) onMessageCallMissed(ctx context.Context, event cloudevents.Event) error {+ ctx, span, _ := listener.tracer.StartWithLogger(ctx, listener.logger)+ defer span.End()++ var payload events.MessageCallMissedPayload+ if err := event.DataAs(&payload); err != nil {+ msg := fmt.Sprintf("cannot decode [%s] into [%T]", event.Data(), payload)+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ if err := listener.client.Trigger(payload.UserID.String(), event.Type(), event.ID()); err != nil {+ msg := fmt.Sprintf("cannot trigger websocket [%s] event with ID [%s] for user with ID [%s]", event.Type(), event.ID(), payload.UserID)+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }+ return nil+}+```++- [ ] **Step 5: Add listener tests**++Create `api/pkg/listeners/read_receipts_test_helpers_test.go`:++```go+package listeners++import (+ "context"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/google/uuid"+ "go.opentelemetry.io/otel/trace"+)++type noopListenerLogger struct{}++func (logger *noopListenerLogger) Error(error) {}+func (logger *noopListenerLogger) WithService(string) telemetry.Logger { return logger }+func (logger *noopListenerLogger) WithString(string, string) telemetry.Logger { return logger }+func (logger *noopListenerLogger) WithSpan(trace.SpanContext) telemetry.Logger { return logger }+func (logger *noopListenerLogger) Trace(string) {}+func (logger *noopListenerLogger) Info(string) {}+func (logger *noopListenerLogger) Warn(error) {}+func (logger *noopListenerLogger) Debug(string) {}+func (logger *noopListenerLogger) Fatal(error) {}+func (logger *noopListenerLogger) Printf(string, ...interface{}) {}++type listenerMessageThreadRepository struct {+ activity repositories.MessageThreadActivityUpdate+}++func (repository *listenerMessageThreadRepository) Store(context.Context, *entities.MessageThread) error {+ return nil+}++func (repository *listenerMessageThreadRepository) UpdateActivity(_ context.Context, params repositories.MessageThreadActivityUpdate) error {+ repository.activity = params+ return nil+}++func (repository *listenerMessageThreadRepository) UpdateStatus(context.Context, entities.UserID, uuid.UUID, repositories.MessageThreadStatusUpdate) error {+ return nil+}++func (repository *listenerMessageThreadRepository) UpdateAfterDeletedMessage(context.Context, repositories.MessageThreadDeletedUpdate) error {+ return nil+}++func (repository *listenerMessageThreadRepository) LoadByOwnerContact(context.Context, entities.UserID, string, string) (*entities.MessageThread, error) {+ return &entities.MessageThread{ID: uuid.New()}, nil+}++func (repository *listenerMessageThreadRepository) Load(context.Context, entities.UserID, uuid.UUID) (*entities.MessageThread, error) {+ return &entities.MessageThread{}, nil+}++func (repository *listenerMessageThreadRepository) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {+ threads := []entities.MessageThread{}+ return &threads, nil+}++func (repository *listenerMessageThreadRepository) Delete(context.Context, entities.UserID, uuid.UUID) error {+ return nil+}++func (repository *listenerMessageThreadRepository) DeleteAllForUser(context.Context, entities.UserID) error {+ return nil+}+```++Create `api/pkg/listeners/message_thread_listener_test.go`:++```go+package listeners++import (+ "context"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ cloudevents "github.com/cloudevents/sdk-go/v2"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestMessageThreadListenerMarksMissedCallUnread(t *testing.T) {+ repository := &listenerMessageThreadRepository{}+ logger := &noopListenerLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ service := services.NewMessageThreadService(logger, tracer, repository, nil)+ _, routes := NewMessageThreadListener(logger, tracer, service)++ event := cloudevents.NewEvent()+ event.SetID(uuid.NewString())+ event.SetSource("/v1/messages/call-missed")+ event.SetType(events.MessageCallMissed)+ event.SetTime(time.Date(2026, 7, 18, 7, 0, 0, 0, time.UTC))+ require.NoError(t, event.SetData(cloudevents.ApplicationJSON, events.MessageCallMissedPayload{+ MessageID: uuid.New(),+ UserID: entities.UserID("user-id"),+ Owner: "+18005550199",+ Contact: "+18005550100",+ Timestamp: time.Date(2026, 7, 18, 6, 59, 0, 0, time.UTC),+ }))++ err := routes[events.MessageCallMissed](context.Background(), event)++ require.NoError(t, err)+ assert.True(t, repository.activity.MarksUnread)+ assert.Equal(t, "Missed phone call", repository.activity.Content)+ assert.Equal(t, event.Time(), repository.activity.EventTimestamp)+}+```++Create `api/pkg/listeners/websocket_listener_test.go`:++```go+package listeners++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/pusher/pusher-http-go/v5"+ "github.com/stretchr/testify/assert"+)++func TestWebsocketListenerRegistersMissedCalls(t *testing.T) {+ logger := &noopListenerLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ _, routes := NewWebsocketListener(logger, tracer, &pusher.Client{})++ assert.Contains(t, routes, events.MessageCallMissed)+}+```++- [ ] **Step 6: Run service and listener tests**++Run:++```powershell+go test ./pkg/services ./pkg/listeners -run 'MessageThread|MissedCall|UpdateStatus|CreateThread' -v+```++Expected: PASS.++- [ ] **Step 7: Commit service and realtime behavior**++```powershell+git add api/pkg/services/message_thread_service.go api/pkg/services/message_thread_service_test.go api/pkg/listeners/message_thread_listener.go api/pkg/listeners/read_receipts_test_helpers_test.go api/pkg/listeners/message_thread_listener_test.go api/pkg/listeners/websocket_listener.go api/pkg/listeners/websocket_listener_test.go+@'+feat(api): track unread inbound threads++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 4: Finish the HTTP behavior and regenerate Swagger++**Files:**++- Modify: `api/pkg/handlers/message_thread_handler.go`+- Modify: `api/docs/docs.go`+- Modify: `api/docs/swagger.json`+- Modify: `api/docs/swagger.yaml`++**Interfaces:**++- Consumes: `responses.MessageThreadResponse` from Task 1.+- Produces: 404 behavior for missing thread updates.+- Produces: Swagger schema fields `is_read`, optional `is_archived`, optional `is_read`.++- [ ] **Step 1: Update the handler error mapping and annotations**++Change the update annotation:++```go+// @Success 200 {object} responses.MessageThreadResponse+// @Failure 404 {object} responses.NotFound+```++Change the error block:++```go+thread, err := h.service.UpdateStatus(ctx, request.ToUpdateParams(h.userIDFomContext(c)))+if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {+ return h.responseNotFound(c, fmt.Sprintf("cannot find message thread with ID [%s]", request.MessageThreadID))+}+if err != nil {+ msg := fmt.Sprintf("cannot update message thread with params [%+#v]", request)+ ctxLogger.Error(stacktrace.Propagate(err, msg))+ return h.responseInternalServerError(c)+}+```++- [ ] **Step 2: Regenerate Swagger**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\api'+swag init --requiredByDefault --parseDependency --parseInternal+```++Expected: `api/docs/docs.go`, `api/docs/swagger.json`, and `api/docs/swagger.yaml` update successfully.++- [ ] **Step 3: Run the full API suite**++Run:++```powershell+go test -vet=off ./pkg/entities ./pkg/repositories ./pkg/requests ./pkg/services ./pkg/validators ./pkg/listeners+go test -vet=off ./pkg/handlers -run '^$'+```++Expected: PASS. Vet is disabled because clean `origin/main` has unrelated Go+1.25 non-constant-format vet failures. Handler tests are compile-checked only+because the pre-existing suite expects an API server on `localhost:8000`; Task+7 provides the HTTP integration coverage against the Docker stack.++- [ ] **Step 4: Commit HTTP and documentation changes**++```powershell+git add api/pkg/handlers/message_thread_handler.go api/docs/docs.go api/docs/swagger.json api/docs/swagger.yaml+@'+docs(api): publish thread read state++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 5: Add automatic read updates to the web store++**Files:**++- Modify: `web/shared/types/api.ts`+- Modify: `web/app/stores/threads.ts`++**Interfaces:**++- Consumes: API `PUT /v1/message-threads/{id}` with `{ is_read: true }`.+- Produces: `markThreadRead(threadId: string, force?: boolean): Promise<void>`.++- [ ] **Step 1: Regenerate TypeScript API models**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\web'+pnpm api:models+```++Expected: `EntitiesMessageThread.is_read: boolean` and optional fields on `RequestsMessageThreadUpdate`.++- [ ] **Step 2: Add a typed local replacement helper**++In `web/app/stores/threads.ts`, add:++```ts+function replaceThread(updatedThread: EntitiesMessageThread) {+ const index = threads.value.findIndex(+ (thread) => thread.id === updatedThread.id,+ );+ if (index !== -1) threads.value[index] = updatedThread;+}+```++- [ ] **Step 3: Implement non-silent automatic read persistence**++Add:++```ts+async function markThreadRead(threadId: string, force = false) {+ const thread = threads.value.find((item) => item.id === threadId);+ if (!thread) throw new Error(`Cannot find thread with id ${threadId}`);+ if (!force && thread.is_read) return;++ try {+ const response = await apiFetch<{ data: EntitiesMessageThread }>(+ `/v1/message-threads/${threadId}`,+ {+ method: "PUT",+ body: { is_read: true },+ },+ );+ replaceThread(response.data);+ } catch (error) {+ notificationsStore.addNotification({+ message: "The message thread could not be marked as read",+ type: "error",+ });+ await loadThreads();+ throw error;+ }+}+```++Add `markThreadRead` to the returned store API.++Keep archive updates independent:++```ts+body: { is_archived: payload.isArchived },+```++Do not send `is_read` from `updateThread`.++- [ ] **Step 4: Run web static checks**++Run:++```powershell+pnpm lint:js+pnpm lint:prettier+```++Expected: PASS.++- [ ] **Step 5: Commit store and generated types**++```powershell+git add web/shared/types/api.ts web/app/stores/threads.ts+@'+feat(web): persist opened threads as read++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 6: Mark opened threads read and highlight unread threads++**Files:**++- Modify: `web/app/pages/threads/[id]/index.vue`+- Modify: `web/app/components/MessageThread.vue`++**Interfaces:**++- Consumes: `threadsStore.markThreadRead(threadId, force)`.+- Produces: automatic initial and realtime read updates.+- Produces: shared unread list styling on mobile and desktop.++- [ ] **Step 1: Make read updates independent from message loading**++In `web/app/pages/threads/[id]/index.vue`, add:++```ts+async function markCurrentThreadRead(force = false) {+ const threadId = route.params.id as string;+ try {+ await threadsStore.markThreadRead(threadId, force);+ } catch (error) {+ console.error(error);+ }+}+```++At the start of `loadMessages`, after computing `threadId`, call without awaiting:++```ts+void markCurrentThreadRead();+```++This lets message loading continue even if the read update fails.++- [ ] **Step 2: Force a newer read watermark after inbound realtime events**++Change the incoming SMS binding:++```ts+webhookChannel.bind("message.phone.received", () => {+ if (!loadingMessages.value) {+ void markCurrentThreadRead(true);+ loadMessages(false);+ }+});+```++Add the missed-call binding with the same behavior:++```ts+webhookChannel.bind("message.call.missed", () => {+ if (!loadingMessages.value) {+ void markCurrentThreadRead(true);+ loadMessages(false);+ }+});+```++The forced call is required because the local thread may still say `is_read:+true` when the concurrent backend listener has not committed its unread update.++- [ ] **Step 3: Add unread presentation**++In `MessageThread.vue`, add the class binding to `v-list-item`:++```vue+:class="{ 'message-thread--unread': !thread.is_read }"+```++Change title and subtitle class bindings:++```vue+<v-list-item-title :class="{ 'font-weight-bold': !thread.is_read }">+ {{ formatPhoneNumber(thread.contact) }}+</v-list-item-title>+<v-list-item-subtitle+ class="text-truncate mt-1"+ :class="{ 'font-weight-bold': !thread.is_read }"+ style="max-width: 250px"+>+```++Add:++```vue+<style scoped>+.message-thread--unread {+ background: rgba(var(--v-theme-primary), 0.1);+}+</style>+```++- [ ] **Step 4: Run web validation**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\web'+pnpm lint+pnpm run generate+```++Expected: both commands PASS.++- [ ] **Step 5: Commit UI behavior**++```powershell+git add web/app/pages/threads/[id]/index.vue web/app/components/MessageThread.vue+@'+feat(web): highlight unread message threads++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 7: Add integration coverage++**Files:**++- Create: `tests/read_receipts_test.go`+- Modify: `tests/README.md`++**Interfaces:**++- Consumes: thread index and update HTTP endpoints from Tasks 1-4.+- Consumes: incoming SMS, missed-call, and outbound message flows from Task 3.+- Produces: `TestMessageThreadReadReceipts`.++- [ ] **Step 1: Write the end-to-end read-receipts test**++Create `tests/read_receipts_test.go`:++```go+package tests++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "net/url"+ "testing"+ "time"++ httpsms "github.com/NdoleStudio/httpsms-go"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type integrationMessageThread struct {+ ID string `json:"id"`+ Contact string `json:"contact"`+ IsRead bool `json:"is_read"`+ LastMessageContent *string `json:"last_message_content"`+}++func requestJSON(+ ctx context.Context,+ t *testing.T,+ method string,+ path string,+ apiKey string,+ payload any,+ expectedStatus int,+ output any,+) {+ t.Helper()++ var body io.Reader+ if payload != nil {+ encoded, err := json.Marshal(payload)+ require.NoError(t, err)+ body = bytes.NewReader(encoded)+ }++ request, err := http.NewRequestWithContext(ctx, method, apiBaseURL+path, body)+ require.NoError(t, err)+ request.Header.Set("x-api-key", apiKey)+ request.Header.Set("Content-Type", "application/json")++ 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, expectedStatus, response.StatusCode, "response: %s", string(responseBody))++ if output != nil {+ require.NoError(t, json.Unmarshal(responseBody, output))+ }+}++func fetchMessageThreads(ctx context.Context, t *testing.T, owner string) []integrationMessageThread {+ t.Helper()++ var response struct {+ Data []integrationMessageThread `json:"data"`+ }+ path := fmt.Sprintf(+ "/v1/message-threads?owner=%s&skip=0&limit=20&is_archived=false",+ url.QueryEscape(owner),+ )+ requestJSON(ctx, t, http.MethodGet, path, userAPIKey, nil, http.StatusOK, &response)+ return response.Data+}++func waitForMessageThread(+ ctx context.Context,+ t *testing.T,+ owner string,+ contact string,+ timeout time.Duration,+ matches func(integrationMessageThread) bool,+) integrationMessageThread {+ t.Helper()++ deadline := time.Now().Add(timeout)+ for time.Now().Before(deadline) {+ for _, thread := range fetchMessageThreads(ctx, t, owner) {+ if thread.Contact == contact && matches(thread) {+ return thread+ }+ }+ time.Sleep(500 * time.Millisecond)+ }++ t.Fatalf("thread %s -> %s did not reach the expected state within %v", owner, contact, timeout)+ return integrationMessageThread{}+}++func markMessageThreadRead(ctx context.Context, t *testing.T, threadID string) integrationMessageThread {+ t.Helper()++ var response struct {+ Data integrationMessageThread `json:"data"`+ }+ requestJSON(+ ctx,+ t,+ http.MethodPut,+ "/v1/message-threads/"+threadID,+ userAPIKey,+ map[string]any{"is_read": true},+ http.StatusOK,+ &response,+ )+ return response.Data+}++func TestMessageThreadReadReceipts(t *testing.T) {+ ctx := context.Background()+ phone := setupPhone(ctx, t, 60)+ contact := randomPhoneNumber()++ requestJSON(+ ctx,+ t,+ http.MethodPost,+ "/v1/messages/receive",+ phone.PhoneAPIKey,+ map[string]any{+ "from": contact,+ "to": phone.PhoneNumber,+ "content": "Unread inbound message",+ "encrypted": false,+ "sim": "SIM1",+ "timestamp": time.Now().UTC().Format(time.RFC3339),+ },+ http.StatusOK,+ nil,+ )++ thread := waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 20*time.Second, func(thread integrationMessageThread) bool {+ return !thread.IsRead+ })+ assert.False(t, thread.IsRead)++ updated := markMessageThreadRead(ctx, t, thread.ID)+ assert.True(t, updated.IsRead)+ waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 10*time.Second, func(thread integrationMessageThread) bool {+ return thread.IsRead+ })++ requestJSON(+ ctx,+ t,+ http.MethodPost,+ "/v1/messages/calls/missed",+ phone.PhoneAPIKey,+ map[string]any{+ "from": contact,+ "to": phone.PhoneNumber,+ "sim": "SIM1",+ "timestamp": time.Now().UTC().Format(time.RFC3339),+ },+ http.StatusOK,+ nil,+ )++ thread = waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 20*time.Second, func(thread integrationMessageThread) bool {+ return !thread.IsRead &&+ thread.LastMessageContent != nil &&+ *thread.LastMessageContent == "Missed phone call"+ })+ assert.False(t, thread.IsRead)++ outboundContent := "Outbound activity preserves unread"+ client := newAPIClient()+ _, response, err := client.Messages.Send(ctx, &httpsms.MessageSendParams{+ From: phone.PhoneNumber,+ To: contact,+ Content: outboundContent,+ })+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, response.HTTPResponse.StatusCode)++ thread = waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 20*time.Second, func(thread integrationMessageThread) bool {+ return thread.LastMessageContent != nil &&+ *thread.LastMessageContent == outboundContent+ })+ assert.False(t, thread.IsRead, "outbound activity must not clear unread state")+}+```++- [ ] **Step 2: Run the test before implementation is complete**++With the Docker integration stack running, execute:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\tests'+go test -v -timeout 120s -run TestMessageThreadReadReceipts ./...+```++Expected before the feature implementation: FAIL because thread responses do not expose/persist `is_read`.++- [ ] **Step 3: Update integration-test documentation**++Add to the Test Coverage checklist in `tests/README.md`:++```markdown+- [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+```++- [ ] **Step 4: Run the integration test against the completed stack**++Generate credentials, start the Docker stack, run the focused test, and tear down:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\tests'+& 'C:\Program Files\Git\bin\bash.exe' generate-firebase-credentials.sh+$env:FIREBASE_CREDENTIALS = (Get-Content firebase-credentials.json -Raw | ConvertFrom-Json | ConvertTo-Json -Compress)+docker compose up -d --build --wait+docker compose wait seed+Start-Sleep -Seconds 2+try {+ go test -v -timeout 120s -run TestMessageThreadReadReceipts ./...+} finally {+ docker compose down -v+}+```++Expected: PASS.++- [ ] **Step 5: Commit integration coverage**++```powershell+git add tests/read_receipts_test.go tests/README.md+@'+test: cover message thread read receipts++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```++### Task 8: Verify the complete feature++**Files:**++- Review: all files changed since `origin/main`++**Interfaces:**++- Consumes: all previous tasks.+- Produces: a clean, verified feature branch.++- [ ] **Step 1: Run API formatting and tests**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\api'+go-fumpt -w pkg/entities/message_thread.go pkg/entities/message_thread_test.go pkg/repositories/message_thread_repository.go pkg/repositories/gorm_message_thread_repository.go pkg/repositories/gorm_message_thread_repository_test.go pkg/services/message_thread_service.go pkg/services/message_thread_service_test.go pkg/requests/message_thread_update_request.go pkg/requests/message_thread_update_request_test.go pkg/validators/message_thread_handler_validator.go pkg/validators/message_thread_handler_validator_test.go pkg/responses/message_thead_responses.go pkg/handlers/message_thread_handler.go pkg/listeners/message_thread_listener.go pkg/listeners/read_receipts_test_helpers_test.go pkg/listeners/message_thread_listener_test.go pkg/listeners/websocket_listener.go pkg/listeners/websocket_listener_test.go+go test -vet=off ./pkg/entities ./pkg/repositories ./pkg/requests ./pkg/services ./pkg/validators ./pkg/listeners+go test -vet=off ./pkg/handlers -run '^$'+```++Expected: formatting completes and all API tests PASS.++- [ ] **Step 2: Run complete web validation**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts\web'+pnpm lint+pnpm run generate+```++Expected: PASS.++- [ ] **Step 3: Inspect the final diff**++Run:++```powershell+Set-Location 'C:\Users\achoa\Work\NdoleStudio\httpsms-read-receipts'+git --no-pager diff --check origin/main...HEAD+git --no-pager diff --stat origin/main...HEAD+git --no-pager status --short --branch+```++Expected: no whitespace errors and no uncommitted implementation changes.++- [ ] **Step 4: Perform manual acceptance checks against a migrated local database**++Verify:++1. Existing rows return `"is_read": true`.+2. A closed thread becomes highlighted after an incoming SMS.+3. A closed thread becomes highlighted after a missed call.+4. Opening the thread removes the highlight and refresh keeps it read.+5. Incoming activity while the thread is open does not leave it unread.+6. Sending and delivery-status changes do not clear an unread thread.+7. Archiving and unarchiving preserve read state.++- [ ] **Step 5: Commit any formatting-only corrections**++Skip this step when Step 1 produced no changes. Otherwise:++```powershell+git add api web+@'+style: format read receipts changes++Co-authored-by: Copilot <[email protected]>+Copilot-Session: bf00a0ac-e11f-4015-b295-3cdd9b491229+'@ | git commit -F -+```diff --git a/docs/superpowers/specs/2026-07-18-read-receipts-design.md b/docs/superpowers/specs/2026-07-18-read-receipts-design.mdnew file mode 100644index 00000000..6462cbaa--- /dev/null+++ b/docs/superpowers/specs/2026-07-18-read-receipts-design.md@@ -0,0 +1,286 @@+# Message Thread Read Receipts++- Date: 2026-07-18+- Status: Approved (design)+- Scope: `api/` Go backend and `web/` Nuxt frontend. Android is unchanged.+- Branch: `feat/read-receipts`, based on `origin/main`++## Problem++The message-thread list does not distinguish conversations with unseen inbound+activity from conversations the user has already opened. Users need unread+threads to stand out and become read automatically when opened.++The change must be backward compatible: every thread that exists when the new+schema is deployed starts as read.++## Decisions++- Unread state is stored per message thread.+- Existing threads are read after migration.+- A new incoming SMS or missed call marks its thread unread.+- Outbound messages and later delivery/status updates do not change read state.+- Opening a thread in the web UI marks it read automatically.+- A thread that receives inbound activity while already open remains read.+- There is no manual "Mark as read/unread" UI.+- Unread threads use bold contact/preview text and a subtle primary-tinted+ background.+- The existing `PUT /v1/message-threads/{messageThreadID}` endpoint handles the+ read update; no new endpoint is added.++## Design++### 1. Thread persistence++Add these fields to `api/pkg/entities/message_thread.go`:++```go+IsRead bool `json:"is_read" gorm:"not null;default:true" example:"true"`+LastReadAt time.Time `json:"-" gorm:"not null;default:CURRENT_TIMESTAMP"`+```++`IsRead` is the public binary state used by API clients and the web UI.+`LastReadAt` is internal ordering metadata used to make concurrent event+processing deterministic.++GORM `AutoMigrate` adds both columns. The database defaults make all existing+rows read and give them a migration-time read watermark. New-thread creation+sets `IsRead` explicitly according to whether the triggering activity is+inbound.++Existing-row updates must not use the repository's current full-row `Save`+method. A stale entity loaded by one event handler could otherwise overwrite a+newer read action from the web request.++### 2. Atomic repository updates++Add field-scoped repository operations for the two update paths:++- **Message activity update:** update only `order_timestamp`,+ `last_message_id`, `last_message_content`, and `status`. For inbound activity,+ conditionally set `is_read = false` only where the stored `last_read_at` is+ older than the CloudEvent creation time.+- **User status update:** update only the supplied `is_archived` and `is_read`+ fields. Marking read writes `is_read = true` and `last_read_at = now` in the+ same database update.++The message activity update runs its metadata and conditional unread statements+inside one GORM transaction. Both operations remain scoped by `user_id` and+thread ID and use GORM's query builder with context propagation.++After a user status update, reload the thread for the API response. Do not use+`Save` in either path, because it writes unrelated columns and reintroduces lost+updates.++The stored timestamp condition prevents this race:++1. An inbound event is created.+2. The websocket listener notifies the open web page.+3. The web page marks the thread read.+4. The message-thread listener finishes later.++Because CloudEvent creation time precedes the read request, the late listener+checks the newer database watermark and does not overwrite the read action. If+the message listener commits first, the later read update wins normally.++### 3. Thread update parameters++Extend `services.MessageThreadUpdateParams` with:++```go+MarksUnread bool+EventTimestamp time.Time+```++Inbound SMS and missed-call listeners set `MarksUnread = true` and use+`event.Time()` as `EventTimestamp`. Other message events leave `MarksUnread`+false, so sending, scheduling, delivery, failure, and expiry updates preserve+the current read state.++For an existing thread, the service delegates the field-scoped message update+and optional conditional unread transition to the repository.++For a newly created thread:++- inbound SMS or missed call: `IsRead = false`;+- outbound activity: `IsRead = true`.++### 4. Missed-call thread updates++`MessageThreadListener` currently handles received SMS events but not+`message.call.missed`. Register the missed-call event and update/create the+corresponding thread with:++- owner and contact from `MessageCallMissedPayload`;+- message ID and event timestamp;+- received status;+- a concise preview such as `Missed phone call`;+- `MarksUnread = true`.++This ensures a missed call is visible as thread activity even when no auto-reply+is configured.++### 5. Existing update endpoint++Change `requests.MessageThreadUpdate` to use optional fields:++```go+IsArchived *bool `json:"is_archived,omitempty" example:"true"`+IsRead *bool `json:"is_read,omitempty" example:"true"`+```++The validator requires at least one supported field. Pointer fields distinguish+"not supplied" from `false`, preventing a read-only update from unarchiving a+thread and an archive-only update from changing read state.++`MessageThreadStatusParams` receives the optional fields. `UpdateStatus`:++- loads the authenticated user's thread;+- builds an update map containing only supplied fields;+- writes `last_read_at = time.Now().UTC()` alongside `is_read = true`;+- supports `IsRead = false` at the API level without adding a web control;+- persists one combined partial update and reloads the updated thread.++The handler preserves repository error codes so a missing thread returns 404.+Invalid IDs or empty/unsupported update bodies return validation errors.++### 6. Web store behavior++Regenerate the API model so `EntitiesMessageThread` includes `is_read` and+`RequestsMessageThreadUpdate` has optional `is_archived` and `is_read`.++In `web/app/stores/threads.ts`:++- keep archive updates on the existing endpoint with+ `{ is_archived: value }`;+- add `markThreadRead(threadId)` using `{ is_read: true }`;+- replace the matching thread in local state with the successful API response;+- make the operation idempotent and skip the request when the local thread is+ already read unless it is called after an inbound realtime event.++Opening a thread invokes `markThreadRead` automatically as part of the thread+loading flow. Message fetching remains independent: if the read update fails,+messages still display, the thread remains/reloads as unread, and the existing+notification system reports the failure.++### 7. Realtime behavior++The message detail page already reloads messages for incoming SMS websocket+events. That reload also marks the currently selected thread read.++Add `message.call.missed` to:++- `WebsocketListener` registrations in the API;+- the Pusher bindings on the thread detail page.++The websocket payload can remain the event ID. The selected thread is marked+read idempotently after any inbound realtime refresh; a different thread's+backend state remains unread.++### 8. Thread-list presentation++In `web/app/components/MessageThread.vue`, unread list items receive:++- bold contact title;+- bold message preview;+- a subtle background using the Vuetify primary theme color at low opacity.++Read threads retain the current appearance. Active-route styling remains+visible and takes precedence where Vuetify applies it.++The highlight is applied in the shared thread-list component, so it works in+both the mobile thread page and desktop navigation drawer, including archived+threads.++### 9. Swagger and generated types++After changing the entity and request annotations:++1. Run `swag init --requiredByDefault --parseDependency --parseInternal` in+ `api/`.+2. Run `pnpm api:models` in `web/`.++Generated Swagger files and `web/shared/types/api.ts` are committed with the+implementation.++## Error Handling++- Repository and service errors continue to use `stacktrace.Propagate`.+- The update handler returns 404 for a thread that does not belong to the+ authenticated user.+- A failed automatic read update is not swallowed and does not block message+ display.+- Local UI state changes only from a successful response or a subsequent thread+ reload; the UI does not claim a persisted read state after an API failure.+- Realtime callbacks report failures through the existing notification/error+ path rather than using empty catches.++## Testing++### API++Add targeted tests for:++- entity schema defaults and new-thread read-state initialization;+- an inbound SMS making an existing thread unread;+- a missed call creating or updating an unread thread;+- outbound and delivery/status events preserving read state;+- a read action winning when its timestamp is newer than an inbound event;+- concurrent message/read updates changing only their owned columns;+- archive-only updates preserving read state;+- read-only updates preserving archive state;+- missing threads preserving the not-found error code;+- existing-row migration defaults (`is_read = true`).++Run:++```bash+cd api+go test ./...+```++### Web++No frontend unit-test runner is configured. Validate the generated types,+Pinia/Vue changes, styles, and production output with:++```bash+cd web+pnpm lint+pnpm run generate+```++### Integration++Add `tests/read_receipts_test.go` to exercise the feature against the Docker+integration stack:++- an inbound SMS creates or updates an unread thread;+- marking the thread read through the existing update endpoint persists;+- a missed call makes the thread unread again;+- subsequent outbound activity does not clear that unread state.++Update `tests/README.md` coverage and run:++```bash+cd tests+go test -v -timeout 120s -run TestMessageThreadReadReceipts ./...+```++Manual acceptance checks:++1. Existing threads appear read immediately after migration.+2. A new incoming SMS highlights its closed thread.+3. A missed call highlights its closed thread.+4. Opening an unread thread removes the highlight and persists across refresh.+5. Incoming activity in the currently open thread does not leave it unread.+6. Sending or receiving delivery updates does not clear another unread state.+7. Archiving/unarchiving does not change read state.++## Out of Scope++- Per-message read receipts.+- Android read/unread UI.+- Unread counts or badges outside the thread list.+- Manual read/unread controls.+- Cross-user/group-conversation receipt tracking.diff --git a/tests/README.md b/tests/README.mdindex 345d84d1..45bbb278 100644--- a/tests/README.md+++ b/tests/README.md@@ -53,6 +53,7 @@ The API's Firebase SDK is configured (via `FCM_ENDPOINT` env var) to redirect al- [x] **Send SMS E2E** — Full send lifecycle: API → FCM push → emulator responds with SENT/DELIVERED events → message reaches `delivered` status- [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## Prerequisitesdiff --git a/tests/read_receipts_test.go b/tests/read_receipts_test.gonew file mode 100644index 00000000..a65e7eb7--- /dev/null+++ b/tests/read_receipts_test.go@@ -0,0 +1,206 @@+package tests++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "net/url"+ "testing"+ "time"++ httpsms "github.com/NdoleStudio/httpsms-go"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type integrationMessageThread struct {+ ID string `json:"id"`+ Contact string `json:"contact"`+ IsRead bool `json:"is_read"`+ LastMessageContent *string `json:"last_message_content"`+}++func requestJSON(+ ctx context.Context,+ t *testing.T,+ method string,+ path string,+ apiKey string,+ payload any,+ expectedStatus int,+ output any,+) {+ t.Helper()++ var encoded []byte+ if payload != nil {+ var err error+ encoded, err = json.Marshal(payload)+ require.NoError(t, err)+ }++ deadline := time.Now().Add(20 * time.Second)+ for {+ request, err := http.NewRequestWithContext(ctx, method, apiBaseURL+path, bytes.NewReader(encoded))+ require.NoError(t, err)+ request.Header.Set("x-api-key", apiKey)+ request.Header.Set("Content-Type", "application/json")++ response, err := http.DefaultClient.Do(request)+ require.NoError(t, err)++ responseBody, err := io.ReadAll(response.Body)+ response.Body.Close()+ require.NoError(t, err)++ if response.StatusCode == http.StatusUnauthorized &&+ apiKey != userAPIKey &&+ time.Now().Before(deadline) {+ time.Sleep(500 * time.Millisecond)+ continue+ }++ require.Equal(t, expectedStatus, response.StatusCode, "response: %s", string(responseBody))+ if output != nil {+ require.NoError(t, json.Unmarshal(responseBody, output))+ }+ return+ }+}++func fetchMessageThreads(ctx context.Context, t *testing.T, owner string) []integrationMessageThread {+ t.Helper()++ var response struct {+ Data []integrationMessageThread `json:"data"`+ }+ path := fmt.Sprintf(+ "/v1/message-threads?owner=%s&skip=0&limit=20&is_archived=false",+ url.QueryEscape(owner),+ )+ requestJSON(ctx, t, http.MethodGet, path, userAPIKey, nil, http.StatusOK, &response)+ return response.Data+}++func waitForMessageThread(+ ctx context.Context,+ t *testing.T,+ owner string,+ contact string,+ timeout time.Duration,+ matches func(integrationMessageThread) bool,+) integrationMessageThread {+ t.Helper()++ deadline := time.Now().Add(timeout)+ for time.Now().Before(deadline) {+ for _, thread := range fetchMessageThreads(ctx, t, owner) {+ if thread.Contact == contact && matches(thread) {+ return thread+ }+ }+ time.Sleep(500 * time.Millisecond)+ }++ t.Fatalf("thread %s -> %s did not reach the expected state within %v", owner, contact, timeout)+ return integrationMessageThread{}+}++func markMessageThreadRead(ctx context.Context, t *testing.T, threadID string) integrationMessageThread {+ t.Helper()++ var response struct {+ Data integrationMessageThread `json:"data"`+ }+ requestJSON(+ ctx,+ t,+ http.MethodPut,+ "/v1/message-threads/"+threadID,+ userAPIKey,+ map[string]any{"is_read": true},+ http.StatusOK,+ &response,+ )+ return response.Data+}++func TestMessageThreadReadReceipts(t *testing.T) {+ ctx := context.Background()+ phone := setupPhone(ctx, t, 60)+ contact := randomPhoneNumber()++ requestJSON(+ ctx,+ t,+ http.MethodPost,+ "/v1/messages/receive",+ phone.PhoneAPIKey,+ map[string]any{+ "from": contact,+ "to": phone.PhoneNumber,+ "content": "Unread inbound message",+ "encrypted": false,+ "sim": "SIM1",+ "timestamp": time.Now().UTC().Format(time.RFC3339Nano),+ },+ http.StatusOK,+ nil,+ )++ thread := waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 20*time.Second, func(thread integrationMessageThread) bool {+ return !thread.IsRead+ })+ assert.False(t, thread.IsRead)++ updated := markMessageThreadRead(ctx, t, thread.ID)+ assert.True(t, updated.IsRead)+ assert.Equal(t, contact, updated.Contact)+ require.NotNil(t, updated.LastMessageContent)+ assert.Equal(t, "Unread inbound message", *updated.LastMessageContent)+ waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 10*time.Second, func(thread integrationMessageThread) bool {+ return thread.IsRead+ })++ requestJSON(+ ctx,+ t,+ http.MethodPost,+ "/v1/messages/calls/missed",+ phone.PhoneAPIKey,+ map[string]any{+ "from": contact,+ "to": phone.PhoneNumber,+ "sim": "SIM1",+ "timestamp": time.Now().UTC().Format(time.RFC3339Nano),+ },+ http.StatusOK,+ nil,+ )++ thread = waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 20*time.Second, func(thread integrationMessageThread) bool {+ return !thread.IsRead &&+ thread.LastMessageContent != nil &&+ *thread.LastMessageContent == "Missed phone call"+ })+ assert.False(t, thread.IsRead)++ outboundContent := "Outbound activity preserves unread"+ client := newAPIClient()+ _, response, err := client.Messages.Send(ctx, &httpsms.MessageSendParams{+ From: phone.PhoneNumber,+ To: contact,+ Content: outboundContent,+ })+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, response.HTTPResponse.StatusCode)++ thread = waitForMessageThread(ctx, t, phone.PhoneNumber, contact, 20*time.Second, func(thread integrationMessageThread) bool {+ return thread.LastMessageContent != nil &&+ *thread.LastMessageContent == outboundContent+ })+ assert.False(t, thread.IsRead, "outbound activity must not clear unread state")+}diff --git a/web/app/components/MessageThread.vue b/web/app/components/MessageThread.vueindex 02959918..2a983431 100644--- a/web/app/components/MessageThread.vue+++ b/web/app/components/MessageThread.vue@@ -99,7 +99,11 @@ function onInstallApp() {:active="threadsStore.threadId === thread.id"><template #prepend>- <v-avatar :color="thread.color" size="40">+ <v-avatar+ :color="thread.color"+ size="40"+ :badge="thread.is_read ? false : { color: 'primary', dotSize: 12 }"+ ><v-icon v-if="!startsWithLetter(thread.contact)" color="white">{{mdiAccount}}</v-icon>@@ -108,11 +112,12 @@ function onInstallApp() {}}</span></v-avatar></template>- <v-list-item-title>{{+ <v-list-item-title :class="{ 'font-weight-bold': !thread.is_read }">{{formatPhoneNumber(thread.contact)}}</v-list-item-title><v-list-item-subtitleclass="text-truncate mt-1"+ :class="{ 'font-weight-bold opacity-100': !thread.is_read }"style="max-width: 250px">{{ thread.last_message_content }}diff --git a/web/app/pages/threads/[id]/index.vue b/web/app/pages/threads/[id]/index.vueindex 1fd11eae..73632a64 100644--- a/web/app/pages/threads/[id]/index.vue+++ b/web/app/pages/threads/[id]/index.vue@@ -112,9 +112,19 @@ function scrollToElement() {hideMessages.value = false}-function loadMessages(hide = true) {+async function markCurrentThreadRead(force = false) {+ const threadId = route.params.id as string+ try {+ await threadsStore.markThreadRead(threadId, force)+ } catch (error) {+ console.error(error)+ }+}++function loadMessages(hide = true, markRead = true) {loadingMessages.value = trueconst threadId = route.params.id as string+ if (markRead) void markCurrentThreadRead()threadsStore.loadThreadMessages(threadId).then((response: EntitiesMessage[]) => {@@ -232,7 +242,16 @@ onMounted(async () => {if (!loadingMessages.value) loadMessages(false)})webhookChannel.bind('message.phone.received', () => {- if (!loadingMessages.value) loadMessages(false)+ if (!loadingMessages.value) {+ void markCurrentThreadRead(true)+ loadMessages(false, false)+ }+ })+ webhookChannel.bind('message.call.missed', () => {+ if (!loadingMessages.value) {+ void markCurrentThreadRead(true)+ loadMessages(false, false)+ }})})diff --git a/web/app/stores/threads.ts b/web/app/stores/threads.tsindex aef2b294..7e300262 100644--- a/web/app/stores/threads.ts+++ b/web/app/stores/threads.ts@@ -24,6 +24,13 @@ export const useThreadsStore = defineStore('threads', () => {return threads.value.find((x) => x.id === id) !== undefined}+ function replaceThread(updatedThread: EntitiesMessageThread) {+ const index = threads.value.findIndex(+ (thread) => thread.id === updatedThread.id,+ )+ if (index !== -1) threads.value[index] = updatedThread+ }+async function loadThreads() {const phonesStore = usePhonesStore()if (phonesStore.owner === null && phonesStore.phones.length === 0) {@@ -93,6 +100,38 @@ export const useThreadsStore = defineStore('threads', () => {})}+ async function markThreadRead(threadId: string, force = false) {+ const thread = threads.value.find((item) => item.id === threadId)+ if (!thread) throw new Error(`Cannot find thread with id ${threadId}`)+ if (!force && thread.is_read) return++ try {+ const response = await apiFetch<{ data: EntitiesMessageThread }>(+ `/v1/message-threads/${threadId}`,+ {+ method: 'PUT',+ body: { is_read: true },+ },+ )+ replaceThread(response.data)+ } catch (error) {+ notificationsStore.addNotification({+ message: 'The message thread could not be marked as read',+ type: 'error',+ })+ try {+ await loadThreads()+ } catch (reloadError) {+ throw new AggregateError(+ [error, reloadError],+ 'Could not mark the message thread as read or reload threads',+ { cause: reloadError },+ )+ }+ throw error+ }+ }+async function deleteThread(id: string) {await apiFetch(`/v1/message-threads/${id}`, { method: 'DELETE' })threadId.value = null@@ -122,6 +161,7 @@ export const useThreadsStore = defineStore('threads', () => {setThreadId,toggleArchive,updateThread,+ markThreadRead,deleteThread,resetState,}diff --git a/web/shared/types/api.ts b/web/shared/types/api.tsindex 3f19b853..27e2db11 100644--- a/web/shared/types/api.ts+++ b/web/shared/types/api.ts@@ -205,6 +205,8 @@ export interface EntitiesMessageThread {id: string;/** @example false */is_archived: boolean;+ /** @example true */+ is_read: boolean;/** @example "This is a sample message content" */last_message_content: string;/** @example "32343a19-da5e-4b1b-a767-3298a73703ca" */@@ -484,7 +486,9 @@ export interface RequestsMessageSendScheduleWindow {export interface RequestsMessageThreadUpdate {/** @example true */- is_archived: boolean;+ is_archived?: boolean;+ /** @example true */+ is_read?: boolean;}export interface RequestsPhoneAPIKeyStoreRequest {@@ -684,6 +688,14 @@ export interface ResponsesMessageSendSchedulesResponse {status: string;}+export interface ResponsesMessageThreadResponse {+ data: EntitiesMessageThread;+ /** @example "Request handled successfully" */+ message: string;+ /** @example "success" */+ status: string;+}+export interface ResponsesMessageThreadsResponse {data: EntitiesMessageThread[];/** @example "Request handled successfully" */