Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
docs: add scheduling send refactor implementation plan
Acho Arnold0d9741de888d
diff --git a/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.md b/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.mdnew file mode 100644index 00000000..a85b46ed--- /dev/null+++ b/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.md@@ -0,0 +1,951 @@+# Scheduling Send Refactor 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:** Allow users to send SMS at an exact time (bypassing scheduling) when `SendAt` is specified, and replace the 1-second bulk hack with rate-based dispatch delays.++**Architecture:** Add a transient `ExactSendTime` flag flowing through the event system. When true, bypass rate-limit and schedule window logic in notification scheduling. For bulk sends without explicit time, compute dispatch delay from `MessagesPerMinute` per-phone instead of hardcoded 1s.++**Tech Stack:** Go, Fiber, GORM, CockroachDB, Google Cloud Tasks (CloudEvents)++**Spec:** `docs/superpowers/specs/2026-05-03-scheduling-send-refactor-design.md`++**Build/Test commands:**++```bash+cd api && go build ./...+cd api && go test -vet=off ./...+```++---++## Task 1: Add ExactSendTime to Event Payload++**Files:**++- Modify: `api/pkg/events/message_api_sent_event.go`++- [ ] **Step 1: Add `ExactSendTime` field to `MessageAPISentPayload`**++In `api/pkg/events/message_api_sent_event.go`, add to the struct:++```go+ExactSendTime bool `json:"exact_send_time"`+```++Add it after line 22 (`ScheduledSendTime *time.Time`).++- [ ] **Step 2: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 3: Commit**++```bash+cd api && git add -A && git commit -m "feat(events): add ExactSendTime field to MessageAPISentPayload"+```++---++## Task 2: Add Index and ExactSendTime to MessageSendParams + Update getSendDelay++**Files:**++- Modify: `api/pkg/services/message_service.go`++- [ ] **Step 1: Add `Index` field to `MessageSendParams`**++In `api/pkg/services/message_service.go` at line ~453, add `Index int` to the struct:++```go+type MessageSendParams struct {+ Owner *phonenumbers.PhoneNumber+ Contact string+ Encrypted bool+ Content string+ Attachments []string+ Source string+ SendAt *time.Time+ RequestID *string+ UserID entities.UserID+ RequestReceivedAt time.Time+ Index int+}+```++- [ ] **Step 2: Update `phoneSettings` to also return `MessagesPerMinute`**++Change the `phoneSettings` method signature and body at line ~1014:++```go+func (service *MessageService) phoneSettings(ctx context.Context, userID entities.UserID, owner string) (uint, entities.SIM, uint) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ ctxLogger := service.tracer.CtxLogger(service.logger, span)++ phone, err := service.phoneService.Load(ctx, userID, owner)+ if err != nil {+ msg := fmt.Sprintf("cannot load phone for userID [%s] and owner [%s]. using default max send attempt of 2", userID, owner)+ ctxLogger.Error(stacktrace.Propagate(err, msg))+ return 2, entities.SIM1, 0+ }++ return phone.MaxSendAttemptsSanitized(), phone.SIM, phone.MessagesPerMinute+}+```++- [ ] **Step 3: Update `SendMessage` to use new `phoneSettings` return value and set `ExactSendTime`**++Update `SendMessage` at line ~467. Key changes: get `messagesPerMinute` from `phoneSettings`, derive `ExactSendTime` from `SendAt != nil`, pass `messagesPerMinute` to `getSendDelay`:++```go+func (service *MessageService) SendMessage(ctx context.Context, params MessageSendParams) (*entities.Message, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ ctxLogger := service.tracer.CtxLogger(service.logger, span)++ sendAttempts, sim, messagesPerMinute := service.phoneSettings(ctx, params.UserID, phonenumbers.Format(params.Owner, phonenumbers.E164))++ eventPayload := events.MessageAPISentPayload{+ MessageID: uuid.New(),+ UserID: params.UserID,+ Encrypted: params.Encrypted,+ MaxSendAttempts: sendAttempts,+ RequestID: params.RequestID,+ Owner: phonenumbers.Format(params.Owner, phonenumbers.E164),+ Contact: params.Contact,+ RequestReceivedAt: params.RequestReceivedAt,+ Content: params.Content,+ Attachments: params.Attachments,+ ScheduledSendTime: params.SendAt,+ ExactSendTime: params.SendAt != nil,+ SIM: sim,+ }++ event, err := service.createMessageAPISentEvent(params.Source, eventPayload)+ if err != nil {+ msg := fmt.Sprintf("cannot create %T from payload with message id [%s]", event, eventPayload.MessageID)+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }+ ctxLogger.Info(fmt.Sprintf("created event [%s] with id [%s] and message id [%s] and user [%s]", event.Type(), event.ID(), eventPayload.MessageID, eventPayload.UserID))++ message, err := service.storeSentMessage(ctx, eventPayload)+ if err != nil {+ msg := fmt.Sprintf("cannot store message with id [%s]", eventPayload.MessageID)+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ timeout := service.getSendDelay(ctxLogger, eventPayload, params, messagesPerMinute)+ if _, err = service.eventDispatcher.DispatchWithTimeout(ctx, event, timeout); err != nil {+ msg := fmt.Sprintf("cannot dispatch event type [%s] and id [%s]", event.Type(), event.ID())+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ ctxLogger.Info(fmt.Sprintf("[%s] event with ID [%s] dispatched succesfully for message [%s] with user [%s] and delay [%s]", event.Type(), event.ID(), eventPayload.MessageID, eventPayload.UserID, timeout))+ return message, err+}+```++- [ ] **Step 4: Rewrite `getSendDelay` to handle rate-based delay**++Replace the existing `getSendDelay` method. New signature takes `messagesPerMinute` as a separate arg:++```go+func (service *MessageService) getSendDelay(ctxLogger telemetry.Logger, eventPayload events.MessageAPISentPayload, params MessageSendParams, messagesPerMinute uint) time.Duration {+ // Exact send time: delay until that time (clamped to 0 if in the past)+ if params.SendAt != nil {+ delay := params.SendAt.Sub(time.Now().UTC())+ if delay < 0 {+ ctxLogger.Info(fmt.Sprintf("message [%s] has send time [%s] in the past. sending immediately", eventPayload.MessageID, params.SendAt.String()))+ return time.Duration(0)+ }+ return delay+ }++ // Rate-based delay for bulk messages (Index > 0)+ if params.Index > 0 && messagesPerMinute > 0 {+ interval := time.Minute / time.Duration(messagesPerMinute)+ delay := time.Duration(params.Index) * interval+ ctxLogger.Info(fmt.Sprintf("message [%s] bulk index [%d] rate-based delay [%s]", eventPayload.MessageID, params.Index, delay))+ return delay+ }++ return time.Duration(0)+}+```++- [ ] **Step 5: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 6: Run tests**++Run: `cd api && go test -vet=off ./...`+Expected: all pass++- [ ] **Step 7: Commit**++```bash+cd api && git add -A && git commit -m "feat(services): add rate-based dispatch delay and ExactSendTime to SendMessage"+```++---++## Task 3: Add ScheduleExact to Repository Interface and Implementation++**Files:**++- Modify: `api/pkg/repositories/phone_notification_repository.go`+- Modify: `api/pkg/repositories/gorm_phone_notification_repository.go`++- [ ] **Step 1: Add `ScheduleExact` to the repository interface**++In `api/pkg/repositories/phone_notification_repository.go`:++```go+// PhoneNotificationRepository loads and persists an entities.PhoneNotification+type PhoneNotificationRepository interface {+ // Schedule a new entities.PhoneNotification+ Schedule(ctx context.Context, messagesPerMinute uint, schedule *entities.MessageSendSchedule, notification *entities.PhoneNotification) error++ // ScheduleExact stores a phone notification with a fixed ScheduledAt time,+ // bypassing rate-limit and schedule window logic.+ ScheduleExact(ctx context.Context, notification *entities.PhoneNotification) error++ // UpdateStatus of a notification+ UpdateStatus(ctx context.Context, notificationID uuid.UUID, status entities.PhoneNotificationStatus) error++ // DeleteAllForUser deletes all entities.PhoneNotification for a user+ DeleteAllForUser(ctx context.Context, userID entities.UserID) error+}+```++- [ ] **Step 2: Implement `ScheduleExact` on `gormPhoneNotificationRepository`**++In `api/pkg/repositories/gorm_phone_notification_repository.go`, add after the `Schedule` method:++```go+// ScheduleExact stores a phone notification with an exact ScheduledAt time.+// It performs a dedupe check — if a pending notification for the same message already exists, it's a no-op.+func (repository *gormPhoneNotificationRepository) ScheduleExact(+ ctx context.Context,+ notification *entities.PhoneNotification,+) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ // Dedupe: check if a pending notification for this message already exists+ var count int64+ if err := repository.db.WithContext(ctx).+ Model(&entities.PhoneNotification{}).+ Where("message_id = ? AND status = ?", notification.MessageID, entities.PhoneNotificationStatusPending).+ Count(&count).Error; err != nil {+ return repository.tracer.WrapErrorSpan(+ span,+ stacktrace.Propagate(err, "cannot check for existing notification for message [%s]", notification.MessageID),+ )+ }++ if count > 0 {+ return nil+ }++ if err := repository.db.WithContext(ctx).Create(notification).Error; err != nil {+ return repository.tracer.WrapErrorSpan(+ span,+ stacktrace.Propagate(err, "cannot create exact-time notification with id [%s]", notification.ID),+ )+ }++ return nil+}+```++- [ ] **Step 3: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 4: Commit**++```bash+cd api && git add -A && git commit -m "feat(repositories): add ScheduleExact method for exact-time notifications"+```++---++## Task 4: Update PhoneNotificationService to Support ExactSendTime++**Files:**++- Modify: `api/pkg/services/phone_notification_service.go`++- [ ] **Step 1: Add fields to `PhoneNotificationScheduleParams`**++Update the struct at line ~162:++```go+// PhoneNotificationScheduleParams are parameters for sending a notification+type PhoneNotificationScheduleParams struct {+ UserID entities.UserID+ Owner string+ Source string+ Encrypted bool+ Contact string+ Content string+ SIM entities.SIM+ MessageID uuid.UUID+ ExactSendTime bool+ ScheduledSendTime *time.Time+}+```++- [ ] **Step 2: Add bypass logic at the start of `Schedule` method**++Update `Schedule` method at line ~175. Add the bypass path after loading the phone:++```go+// Schedule a notification to be sent to a phone+func (service *PhoneNotificationService) Schedule(ctx context.Context, params *PhoneNotificationScheduleParams) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ ctxLogger := service.tracer.CtxLogger(service.logger, span)++ phone, err := service.phoneRepository.Load(ctx, params.UserID, params.Owner)+ if err != nil {+ msg := fmt.Sprintf("cannot load phone with userID [%s] and phone [%s]", params.UserID, params.Owner)+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ notification := &entities.PhoneNotification{+ ID: uuid.New(),+ MessageID: params.MessageID,+ UserID: params.UserID,+ PhoneID: phone.ID,+ Status: entities.PhoneNotificationStatusPending,+ ScheduledAt: time.Now().UTC(),+ CreatedAt: time.Now().UTC(),+ UpdatedAt: time.Now().UTC(),+ }++ // Bypass rate-limit and schedule window logic for exact send time+ if params.ExactSendTime && params.ScheduledSendTime != nil {+ scheduledAt := *params.ScheduledSendTime+ // Clamp past times to now (send immediately)+ if scheduledAt.Before(time.Now().UTC()) {+ scheduledAt = time.Now().UTC()+ }+ notification.ScheduledAt = scheduledAt+ if err = service.phoneNotificationRepository.ScheduleExact(ctx, notification); err != nil {+ msg := fmt.Sprintf("cannot schedule exact notification for message [%s] to phone [%s]", params.MessageID, phone.ID)+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ if err = service.dispatchMessageNotificationScheduled(ctx, params, notification); err != nil {+ ctxLogger.Error(err)+ }++ if err = service.dispatchMessageNotificationSend(ctx, params.Source, notification); err != nil {+ return service.tracer.WrapErrorSpan(span, err)+ }++ ctxLogger.Info(fmt.Sprintf(+ "message with id [%s] exact notification scheduled for [%s] with id [%s]",+ params.MessageID,+ notification.ScheduledAt,+ notification.ID,+ ))+ return nil+ }++ // Standard path: apply rate-limit + schedule window logic+ var schedule *entities.MessageSendSchedule+ if phone.ScheduleID != nil {+ schedule, err = service.sendScheduleRepository.Load(ctx, params.UserID, *phone.ScheduleID)+ if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {+ schedule = nil+ err = nil+ }+ if err != nil {+ msg := fmt.Sprintf("cannot load send schedule [%s] for phone [%s]", *phone.ScheduleID, phone.ID)+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }+ }++ if err = service.phoneNotificationRepository.Schedule(ctx, phone.MessagesPerMinute, schedule, notification); err != nil {+ msg := fmt.Sprintf("cannot schedule notification for message [%s] to phone [%s]", params.MessageID, phone.ID)+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ if err = service.dispatchMessageNotificationScheduled(ctx, params, notification); err != nil {+ ctxLogger.Error(err)+ }++ if err = service.dispatchMessageNotificationSend(ctx, params.Source, notification); err != nil {+ return service.tracer.WrapErrorSpan(span, err)+ }++ ctxLogger.Info(fmt.Sprintf(+ "message with id [%s] notification scheduled for [%s] with id [%s]",+ params.MessageID,+ notification.ScheduledAt,+ notification.ID,+ ))+ return nil+}+```++- [ ] **Step 3: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 4: Commit**++```bash+cd api && git add -A && git commit -m "feat(services): add ExactSendTime bypass in PhoneNotificationService.Schedule"+```++---++## Task 5: Update Phone Notification Listener to Pass ExactSendTime++**Files:**++- Modify: `api/pkg/listeners/phone_notification_listener.go`++- [ ] **Step 1: Pass ExactSendTime and ScheduledSendTime from event payload to service params**++Update the `onMessageAPISent` method at line ~44:++```go+func (listener *PhoneNotificationListener) onMessageAPISent(ctx context.Context, event cloudevents.Event) error {+ ctx, span := listener.tracer.Start(ctx)+ defer span.End()++ var payload events.MessageAPISentPayload+ 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))+ }++ sendParams := &services.PhoneNotificationScheduleParams{+ UserID: payload.UserID,+ Owner: payload.Owner,+ Contact: payload.Contact,+ Content: payload.Content,+ SIM: payload.SIM,+ Encrypted: payload.Encrypted,+ Source: event.Source(),+ MessageID: payload.MessageID,+ ExactSendTime: payload.ExactSendTime,+ ScheduledSendTime: payload.ScheduledSendTime,+ }++ if err := listener.service.Schedule(ctx, sendParams); err != nil {+ msg := fmt.Sprintf("cannot send notification with params [%s] for event with ID [%s]", spew.Sdump(sendParams), event.ID())+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}+```++- [ ] **Step 2: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 3: Commit**++```bash+cd api && git add -A && git commit -m "feat(listeners): pass ExactSendTime to PhoneNotificationService from event"+```++---++## Task 6: Update Bulk Send Request + Handler++**Files:**++- Modify: `api/pkg/requests/message_bulk_send_request.go`+- Modify: `api/pkg/handlers/message_handler.go`++- [ ] **Step 1: Remove per-index SendAt from `MessageBulkSend.ToMessageSendParams()`**++In `api/pkg/requests/message_bulk_send_request.go`, update `ToMessageSendParams`:++```go+// ToMessageSendParams converts MessageSend to services.MessageSendParams+func (input *MessageBulkSend) ToMessageSendParams(userID entities.UserID, source string) []services.MessageSendParams {+ from, _ := phonenumbers.Parse(input.From, phonenumbers.UNKNOWN_REGION)++ var result []services.MessageSendParams+ for index, to := range input.To {+ result = append(result, services.MessageSendParams{+ Source: source,+ Owner: from,+ Encrypted: input.Encrypted,+ RequestID: input.sanitizeStringPointer(input.RequestID),+ UserID: userID,+ RequestReceivedAt: time.Now().UTC(),+ Contact: to,+ Content: input.Content,+ Attachments: input.Attachments,+ Index: index,+ })+ }++ return result+}+```++Key changes: removed `SendAt` assignment and added `Index: index`.++- [ ] **Step 2: Remove the `index * 1s` hack from `BulkSend` handler**++In `api/pkg/handlers/message_handler.go`, update the `BulkSend` handler goroutine (around line 160-175). Remove the `if message.SendAt == nil` block:++Replace:++```go+for index, message := range params {+ wg.Add(1)+ go func(message services.MessageSendParams, index int) {+ count.Add(1)+ if message.SendAt == nil {+ sentAt := time.Now().UTC().Add(time.Duration(index) * time.Second)+ message.SendAt = &sentAt+ }++ response, err := h.service.SendMessage(ctx, message)+```++With:++```go+for index, message := range params {+ wg.Add(1)+ go func(message services.MessageSendParams, index int) {+ count.Add(1)+ response, err := h.service.SendMessage(ctx, message)+```++- [ ] **Step 3: Remove unused `time` import if needed**++Check if `time` is still used in `message_handler.go`. It likely is (used elsewhere), so skip this step if so.++- [ ] **Step 4: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 5: Commit**++```bash+cd api && git add -A && git commit -m "feat(handlers): replace 1s hack with rate-based delay for bulk send"+```++---++## Task 7: Update CSV Bulk Message Request + Handler++**Files:**++- Modify: `api/pkg/requests/bulk_message_request.go`+- Modify: `api/pkg/handlers/bulk_message_handler.go`++- [ ] **Step 1: Add `Index` parameter to `BulkMessage.ToMessageSendParams()`**++In `api/pkg/requests/bulk_message_request.go`, change the method signature to accept index:++```go+// ToMessageSendParams converts BulkMessage to services.MessageSendParams+func (input *BulkMessage) ToMessageSendParams(userID entities.UserID, requestID uuid.UUID, source string, index int) services.MessageSendParams {+ from, _ := phonenumbers.Parse(input.FromPhoneNumber, phonenumbers.UNKNOWN_REGION)++ return services.MessageSendParams{+ Source: source,+ Owner: from,+ RequestID: input.sanitizeStringPointer(fmt.Sprintf("bulk-%s", requestID.String())),+ UserID: userID,+ SendAt: input.SendTime,+ RequestReceivedAt: time.Now().UTC(),+ Contact: input.sanitizeAddress(input.ToPhoneNumber),+ Content: input.Content,+ Attachments: input.removeEmptyStrings(strings.Split(input.AttachmentURLs, ",")),+ Index: index,+ }+}+```++- [ ] **Step 2: Update `BulkMessageHandler.Store()` to compute per-phone index**++In `api/pkg/handlers/bulk_message_handler.go`, update the Store method to compute per-phone indices:++```go+func (h *BulkMessageHandler) Store(c *fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ file, err := c.FormFile("document")+ if err != nil {+ msg := fmt.Sprintf("cannot fetch file with name [%s] from request", "document")+ ctxLogger.Warn(stacktrace.Propagate(err, msg))+ return h.responseBadRequest(c, err)+ }++ messages, validationErrors := h.validator.ValidateStore(ctx, h.userIDFomContext(c), file)+ if len(validationErrors) != 0 {+ msg := fmt.Sprintf("validation errors [%s], while sending bulk sms from CSV file [%s] for [%s]", spew.Sdump(validationErrors), file.Filename, h.userIDFomContext(c))+ ctxLogger.Warn(stacktrace.NewError(msg))+ return h.responseUnprocessableEntity(c, validationErrors, "validation errors while sending bulk SMS")+ }++ if msg := h.billingService.IsEntitledWithCount(ctx, h.userIDFomContext(c), uint(len(messages))); msg != nil {+ ctxLogger.Warn(stacktrace.NewError(fmt.Sprintf("user with ID [%s] is not entitled to send [%d] messages", h.userIDFomContext(c), len(messages))))+ return h.responsePaymentRequired(c, *msg)+ }++ requestID := uuid.New()+ wg := sync.WaitGroup{}+ count := atomic.Int64{}++ // Compute per-phone index for rate-based dispatch delay+ phoneIndexMap := make(map[string]int)+ for _, message := range messages {+ if message.SendTime != nil {+ continue // Exact-time messages don't need indexing+ }+ phone := message.FromPhoneNumber+ phoneIndexMap[phone]++ // Pre-count not needed, we'll compute inline+ }++ // Reset for actual iteration+ phoneIndexCounter := make(map[string]int)++ for _, message := range messages {+ wg.Add(1)+ var perPhoneIndex int+ if message.SendTime == nil {+ perPhoneIndex = phoneIndexCounter[message.FromPhoneNumber]+ phoneIndexCounter[message.FromPhoneNumber]+++ }++ go func(message *requests.BulkMessage, index int) {+ count.Add(1)+ _, err = h.messageService.SendMessage(+ ctx,+ message.ToMessageSendParams(h.userIDFomContext(c), requestID, c.OriginalURL(), index),+ )+ if err != nil {+ count.Add(-1)+ msg := fmt.Sprintf("cannot send message with paylod [%s] at index [%d]", spew.Sdump(message), index)+ ctxLogger.Error(stacktrace.Propagate(err, msg))+ }+ wg.Done()+ }(message, perPhoneIndex)+ }++ wg.Wait()+ return h.responseAccepted(c, fmt.Sprintf("Added %d out of %d messages to the queue", count.Load(), len(messages)))+}+```++- [ ] **Step 3: Clean up unused `phoneIndexMap` variable**++The `phoneIndexMap` is computed but unused. Remove it — we only need `phoneIndexCounter`:++```go+// Compute per-phone index for rate-based dispatch delay+phoneIndexCounter := make(map[string]int)++for _, message := range messages {+ wg.Add(1)+ var perPhoneIndex int+ if message.SendTime == nil {+ perPhoneIndex = phoneIndexCounter[message.FromPhoneNumber]+ phoneIndexCounter[message.FromPhoneNumber]+++ }++ go func(message *requests.BulkMessage, index int) {+ // ... same as above+ }(message, perPhoneIndex)+}+```++- [ ] **Step 4: Build to verify no compile errors**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 5: Run tests**++Run: `cd api && go test -vet=off ./...`+Expected: all pass++- [ ] **Step 6: Commit**++```bash+cd api && git add -A && git commit -m "feat(handlers): add per-phone index for CSV bulk messages"+```++---++## Task 8: Add Unit Tests for getSendDelay++**Files:**++- Create: `api/pkg/services/message_service_test.go`++- [ ] **Step 1: Write tests for the new `getSendDelay` logic**++Create `api/pkg/services/message_service_test.go`:++```go+package services++import (+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "go.opentelemetry.io/otel/trace"+)++func TestGetSendDelay_WithSendAt_ReturnsTimeUntil(t *testing.T) {+ service := &MessageService{}+ logger := &noopLogger{}++ sendAt := time.Now().UTC().Add(5 * time.Minute)+ params := MessageSendParams{SendAt: &sendAt}+ payload := events.MessageAPISentPayload{MessageID: uuid.New()}++ delay := service.getSendDelay(logger, payload, params, 10)++ // Should be approximately 5 minutes (within 2 seconds tolerance)+ assert.InDelta(t, float64(5*time.Minute), float64(delay), float64(2*time.Second))+}++func TestGetSendDelay_WithSendAtInPast_ReturnsZero(t *testing.T) {+ service := &MessageService{}+ logger := &noopLogger{}++ sendAt := time.Now().UTC().Add(-5 * time.Minute)+ params := MessageSendParams{SendAt: &sendAt}+ payload := events.MessageAPISentPayload{MessageID: uuid.New()}++ delay := service.getSendDelay(logger, payload, params, 10)++ assert.Equal(t, time.Duration(0), delay)+}++func TestGetSendDelay_BulkIndex_RateBasedDelay(t *testing.T) {+ service := &MessageService{}+ logger := &noopLogger{}++ params := MessageSendParams{Index: 3}+ payload := events.MessageAPISentPayload{MessageID: uuid.New()}++ // 10 messages per minute = 6 seconds interval+ delay := service.getSendDelay(logger, payload, params, 10)++ expected := time.Duration(3) * (time.Minute / time.Duration(10))+ assert.Equal(t, expected, delay)+}++func TestGetSendDelay_BulkIndex_ZeroRate_ReturnsZero(t *testing.T) {+ service := &MessageService{}+ logger := &noopLogger{}++ params := MessageSendParams{Index: 5}+ payload := events.MessageAPISentPayload{MessageID: uuid.New()}++ delay := service.getSendDelay(logger, payload, params, 0)++ assert.Equal(t, time.Duration(0), delay)+}++func TestGetSendDelay_IndexZero_ReturnsZero(t *testing.T) {+ service := &MessageService{}+ logger := &noopLogger{}++ params := MessageSendParams{Index: 0}+ payload := events.MessageAPISentPayload{MessageID: uuid.New()}++ delay := service.getSendDelay(logger, payload, params, 10)++ assert.Equal(t, time.Duration(0), delay)+}++func TestGetSendDelay_NoSendAtNoIndex_ReturnsZero(t *testing.T) {+ service := &MessageService{}+ logger := &noopLogger{}++ params := MessageSendParams{}+ payload := events.MessageAPISentPayload{MessageID: uuid.New()}++ delay := service.getSendDelay(logger, payload, params, 10)++ assert.Equal(t, time.Duration(0), delay)+}++// noopLogger implements telemetry.Logger for testing+type noopLogger struct{}++var _ telemetry.Logger = (*noopLogger)(nil)++func (l *noopLogger) Error(_ error) {}+func (l *noopLogger) WithService(_ string) telemetry.Logger { return l }+func (l *noopLogger) WithString(_, _ string) telemetry.Logger { return l }+func (l *noopLogger) WithSpan(_ trace.SpanContext) telemetry.Logger { return l }+func (l *noopLogger) Trace(_ string) {}+func (l *noopLogger) Info(_ string) {}+func (l *noopLogger) Warn(_ error) {}+func (l *noopLogger) Debug(_ string) {}+func (l *noopLogger) Fatal(_ error) {}+func (l *noopLogger) Printf(_ string, _ ...interface{}) {}+```++- [ ] **Step 2: Run the tests**++Run: `cd api && go test -vet=off ./pkg/services/ -run TestGetSendDelay -v`+Expected: all pass++- [ ] **Step 3: Commit**++```bash+cd api && git add -A && git commit -m "test(services): add unit tests for getSendDelay rate-based logic"+```++---++## Task 9: Add Unit Test for ResolveScheduledAt (Existing, Verify No Regression)++**Files:**++- Create: `api/pkg/entities/send_schedule_test.go`++- [ ] **Step 1: Write tests to lock existing ResolveScheduledAt behavior**++Create `api/pkg/entities/send_schedule_test.go`:++```go+package entities++import (+ "testing"+ "time"++ "github.com/stretchr/testify/assert"+)++func TestResolveScheduledAt_NilSchedule_ReturnsCurrentUTC(t *testing.T) {+ now := time.Now()+ var schedule *MessageSendSchedule+ result := schedule.ResolveScheduledAt(now)+ assert.Equal(t, now.UTC(), result)+}++func TestResolveScheduledAt_InactiveSchedule_ReturnsCurrentUTC(t *testing.T) {+ now := time.Now()+ schedule := &MessageSendSchedule{IsActive: false}+ result := schedule.ResolveScheduledAt(now)+ assert.Equal(t, now.UTC(), result)+}++func TestResolveScheduledAt_NoWindows_ReturnsCurrentUTC(t *testing.T) {+ now := time.Now()+ schedule := &MessageSendSchedule{+ IsActive: true,+ Timezone: "UTC",+ Windows: []MessageSendScheduleWindow{},+ }+ result := schedule.ResolveScheduledAt(now)+ assert.Equal(t, now.UTC(), result)+}++func TestResolveScheduledAt_WithinWindow_ReturnsCurrentUTC(t *testing.T) {+ // Wednesday at 10:00 UTC, window is Wed 9:00-17:00 (540-1020 minutes)+ now := time.Date(2025, 1, 1, 10, 0, 0, 0, time.UTC) // Wednesday+ schedule := &MessageSendSchedule{+ IsActive: true,+ Timezone: "UTC",+ Windows: []MessageSendScheduleWindow{+ {DayOfWeek: int(now.Weekday()), StartMinute: 540, EndMinute: 1020},+ },+ }+ result := schedule.ResolveScheduledAt(now)+ assert.Equal(t, now.UTC(), result)+}++func TestResolveScheduledAt_BeforeWindow_ReturnsWindowStart(t *testing.T) {+ // Wednesday at 7:00 UTC, window is Wed 9:00-17:00+ now := time.Date(2025, 1, 1, 7, 0, 0, 0, time.UTC) // Wednesday+ schedule := &MessageSendSchedule{+ IsActive: true,+ Timezone: "UTC",+ Windows: []MessageSendScheduleWindow{+ {DayOfWeek: int(now.Weekday()), StartMinute: 540, EndMinute: 1020},+ },+ }+ result := schedule.ResolveScheduledAt(now)+ expected := time.Date(2025, 1, 1, 9, 0, 0, 0, time.UTC)+ assert.Equal(t, expected, result)+}+```++- [ ] **Step 2: Run the tests**++Run: `cd api && go test -vet=off ./pkg/entities/ -run TestResolveScheduledAt -v`+Expected: all pass++- [ ] **Step 3: Commit**++```bash+cd api && git add -A && git commit -m "test(entities): add regression tests for ResolveScheduledAt"+```++---++## Task 10: Final Build + Integration Verification++**Files:** None (verification only)++- [ ] **Step 1: Full build**++Run: `cd api && go build ./...`+Expected: success++- [ ] **Step 2: Full test suite**++Run: `cd api && go test -vet=off ./...`+Expected: all pass++- [ ] **Step 3: Generate Swagger docs (if API annotations changed)**++The API request structs' annotations haven't changed for swagger (no new endpoints, `SendAt` already documented). Skip swagger regen unless compile errors appear.++- [ ] **Step 4: Verify git status is clean**++Run: `cd api && git status`+Expected: clean working tree++---++## Notes++- The `noopLogger` in tests implements the full `telemetry.Logger` interface (Error, WithService, WithString, WithSpan, Trace, Info, Warn, Debug, Fatal, Printf).+- The `ExactSendTime` field is transient — no database migrations needed.+- **Dedupe strategy**: `ScheduleExact` uses a `SELECT COUNT` check before insert. This is not fully race-proof but acceptable given: (a) Cloud Tasks at-least-once duplicates are rare, and (b) the existing `Schedule` path also has this same theoretical gap. Adding a DB unique constraint on `(message_id, status='pending')` would require a partial index migration — this is deferred as a future improvement if duplicates become a problem in practice.+- The existing `Schedule` method already handles concurrency via CockroachDB's serializable transactions (`crdbgorm.ExecuteTx`), which retries automatically on conflicts. No additional dedupe is added there.+- All existing behavior for single messages without `SendAt` is preserved (delay = 0, standard scheduling path).+- Past `SendAt` times are handled at both layers: `getSendDelay` returns 0 (immediate dispatch), and `Schedule` clamps `ScheduledAt` to `now` (no past timestamps persisted).