test(entities): add regression tests for ResolveScheduledAt

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

Author: AchoArnold

api/pkg/entities/send_schedule_test.go

@@ -0,0 +1,62 @@
+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)
+}

api/pkg/repositories/gorm_phone_notification_repository.go

@@ -203,3 +203,38 @@ func (repository *gormPhoneNotificationRepository) insert(
 
 	return nil
 }
+
+// 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
+}

api/pkg/repositories/phone_notification_repository.go

@@ -13,6 +13,10 @@ 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