feat(bot): add secure reminder job runtime

packages/application/src/index.ts

@@ -1,5 +1,10 @@
 export { calculateMonthlySettlement } from './settlement-engine'
 export { createFinanceCommandService, type FinanceCommandService } from './finance-command-service'
+export {
+  createReminderJobService,
+  type ReminderJobResult,
+  type ReminderJobService
+} from './reminder-job-service'
 export {
   parsePurchaseMessage,
   type ParsedPurchaseResult,

packages/application/src/reminder-job-service.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'bun:test'
+
+import type {
+  ClaimReminderDispatchInput,
+  ClaimReminderDispatchResult,
+  ReminderDispatchRepository
+} from '@household/ports'
+
+import { createReminderJobService } from './reminder-job-service'
+
+class ReminderDispatchRepositoryStub implements ReminderDispatchRepository {
+  nextResult: ClaimReminderDispatchResult = {
+    dedupeKey: '2026-03:utilities',
+    claimed: true
+  }
+
+  lastClaim: ClaimReminderDispatchInput | null = null
+
+  async claimReminderDispatch(
+    input: ClaimReminderDispatchInput
+  ): Promise<ClaimReminderDispatchResult> {
+    this.lastClaim = input
+    return this.nextResult
+  }
+}
+
+describe('createReminderJobService', () => {
+  test('returns dry-run result without touching the repository', async () => {
+    const repository = new ReminderDispatchRepositoryStub()
+    const service = createReminderJobService(repository)
+
+    const result = await service.handleJob({
+      householdId: 'household-1',
+      period: '2026-03',
+      reminderType: 'utilities',
+      dryRun: true
+    })
+
+    expect(result.status).toBe('dry-run')
+    expect(result.dedupeKey).toBe('2026-03:utilities')
+    expect(result.messageText).toBe('Utilities reminder for 2026-03')
+    expect(repository.lastClaim).toBeNull()
+  })
+
+  test('claims a dispatch once and returns the dedupe key', async () => {
+    const repository = new ReminderDispatchRepositoryStub()
+    const service = createReminderJobService(repository)
+
+    const result = await service.handleJob({
+      householdId: 'household-1',
+      period: '2026-03',
+      reminderType: 'rent-due'
+    })
+
+    expect(result.status).toBe('claimed')
+    expect(repository.lastClaim).toMatchObject({
+      householdId: 'household-1',
+      period: '2026-03',
+      reminderType: 'rent-due'
+    })
+  })
+
+  test('returns duplicate when the repository rejects a replay', async () => {
+    const repository = new ReminderDispatchRepositoryStub()
+    repository.nextResult = {
+      dedupeKey: '2026-03:rent-warning',
+      claimed: false
+    }
+
+    const service = createReminderJobService(repository)
+    const result = await service.handleJob({
+      householdId: 'household-1',
+      period: '2026-03',
+      reminderType: 'rent-warning'
+    })
+
+    expect(result.status).toBe('duplicate')
+    expect(result.dedupeKey).toBe('2026-03:rent-warning')
+  })
+})

packages/application/src/reminder-job-service.ts

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto'
+
+import { BillingPeriod } from '@household/domain'
+import type {
+  ClaimReminderDispatchResult,
+  ReminderDispatchRepository,
+  ReminderType
+} from '@household/ports'
+
+function computePayloadHash(payload: object): string {
+  return createHash('sha256').update(JSON.stringify(payload)).digest('hex')
+}
+
+function createReminderMessage(reminderType: ReminderType, period: string): string {
+  switch (reminderType) {
+    case 'utilities':
+      return `Utilities reminder for ${period}`
+    case 'rent-warning':
+      return `Rent reminder for ${period}: payment is coming up soon.`
+    case 'rent-due':
+      return `Rent due reminder for ${period}: please settle payment today.`
+  }
+}
+
+export interface ReminderJobResult {
+  status: 'dry-run' | 'claimed' | 'duplicate'
+  dedupeKey: string
+  payloadHash: string
+  reminderType: ReminderType
+  period: string
+  messageText: string
+}
+
+export interface ReminderJobService {
+  handleJob(input: {
+    householdId: string
+    period: string
+    reminderType: ReminderType
+    dryRun?: boolean
+  }): Promise<ReminderJobResult>
+}
+
+export function createReminderJobService(
+  repository: ReminderDispatchRepository
+): ReminderJobService {
+  return {
+    async handleJob(input) {
+      const period = BillingPeriod.fromString(input.period).toString()
+      const payloadHash = computePayloadHash({
+        householdId: input.householdId,
+        period,
+        reminderType: input.reminderType
+      })
+      const messageText = createReminderMessage(input.reminderType, period)
+
+      if (input.dryRun === true) {
+        return {
+          status: 'dry-run',
+          dedupeKey: `${period}:${input.reminderType}`,
+          payloadHash,
+          reminderType: input.reminderType,
+          period,
+          messageText
+        }
+      }
+
+      const result: ClaimReminderDispatchResult = await repository.claimReminderDispatch({
+        householdId: input.householdId,
+        period,
+        reminderType: input.reminderType,
+        payloadHash
+      })
+
+      return {
+        status: result.claimed ? 'claimed' : 'duplicate',
+        dedupeKey: result.dedupeKey,
+        payloadHash,
+        reminderType: input.reminderType,
+        period,
+        messageText
+      }
+    }
+  }
+}