feat(bot): add secure reminder job runtime

apps/bot/src/config.ts

@@ -9,6 +9,8 @@ export interface BotRuntimeConfig {
   telegramPurchaseTopicId?: number
   purchaseTopicIngestionEnabled: boolean
   financeCommandsEnabled: boolean
+  schedulerSharedSecret?: string
+  reminderJobsEnabled: boolean
   openaiApiKey?: string
   parserModel: string
 }
@@ -57,6 +59,7 @@ export function getBotRuntimeConfig(env: NodeJS.ProcessEnv = process.env): BotRu
   const householdId = parseOptionalValue(env.HOUSEHOLD_ID)
   const telegramHouseholdChatId = parseOptionalValue(env.TELEGRAM_HOUSEHOLD_CHAT_ID)
   const telegramPurchaseTopicId = parseOptionalTopicId(env.TELEGRAM_PURCHASE_TOPIC_ID)
+  const schedulerSharedSecret = parseOptionalValue(env.SCHEDULER_SHARED_SECRET)
 
   const purchaseTopicIngestionEnabled =
     databaseUrl !== undefined &&
@@ -65,6 +68,8 @@ export function getBotRuntimeConfig(env: NodeJS.ProcessEnv = process.env): BotRu
     telegramPurchaseTopicId !== undefined
 
   const financeCommandsEnabled = databaseUrl !== undefined && householdId !== undefined
+  const reminderJobsEnabled =
+    databaseUrl !== undefined && householdId !== undefined && schedulerSharedSecret !== undefined
 
   const runtime: BotRuntimeConfig = {
     port: parsePort(env.PORT),
@@ -73,6 +78,7 @@ export function getBotRuntimeConfig(env: NodeJS.ProcessEnv = process.env): BotRu
     telegramWebhookPath: env.TELEGRAM_WEBHOOK_PATH ?? '/webhook/telegram',
     purchaseTopicIngestionEnabled,
     financeCommandsEnabled,
+    reminderJobsEnabled,
     parserModel: env.PARSER_MODEL?.trim() || 'gpt-4.1-mini'
   }
 
@@ -88,6 +94,9 @@ export function getBotRuntimeConfig(env: NodeJS.ProcessEnv = process.env): BotRu
   if (telegramPurchaseTopicId !== undefined) {
     runtime.telegramPurchaseTopicId = telegramPurchaseTopicId
   }
+  if (schedulerSharedSecret !== undefined) {
+    runtime.schedulerSharedSecret = schedulerSharedSecret
+  }
   const openaiApiKey = parseOptionalValue(env.OPENAI_API_KEY)
   if (openaiApiKey !== undefined) {
     runtime.openaiApiKey = openaiApiKey

apps/bot/src/index.ts

@@ -1,7 +1,10 @@
 import { webhookCallback } from 'grammy'
 
-import { createFinanceCommandService } from '@household/application'
-import { createDbFinanceRepository } from '@household/adapters-db'
+import { createFinanceCommandService, createReminderJobService } from '@household/application'
+import {
+  createDbFinanceRepository,
+  createDbReminderDispatchRepository
+} from '@household/adapters-db'
 
 import { createFinanceCommandsService } from './finance-commands'
 import { createTelegramBot } from './bot'
@@ -11,6 +14,7 @@ import {
   createPurchaseMessageRepository,
   registerPurchaseTopicIngestion
 } from './purchase-topic-ingestion'
+import { createReminderJobsHandler } from './reminder-jobs'
 import { createBotWebhookServer } from './server'
 
 const runtime = getBotRuntimeConfig()
@@ -58,10 +62,37 @@ if (runtime.financeCommandsEnabled) {
   console.warn('Finance commands are disabled. Set DATABASE_URL and HOUSEHOLD_ID to enable.')
 }
 
+const reminderJobs = runtime.reminderJobsEnabled
+  ? (() => {
+      const reminderRepositoryClient = createDbReminderDispatchRepository(runtime.databaseUrl!)
+      const reminderService = createReminderJobService(reminderRepositoryClient.repository)
+
+      shutdownTasks.push(reminderRepositoryClient.close)
+
+      return createReminderJobsHandler({
+        householdId: runtime.householdId!,
+        reminderService
+      })
+    })()
+  : null
+
+if (!runtime.reminderJobsEnabled) {
+  console.warn(
+    'Reminder jobs are disabled. Set DATABASE_URL, HOUSEHOLD_ID, and SCHEDULER_SHARED_SECRET to enable.'
+  )
+}
+
 const server = createBotWebhookServer({
   webhookPath: runtime.telegramWebhookPath,
   webhookSecret: runtime.telegramWebhookSecret,
-  webhookHandler
+  webhookHandler,
+  scheduler:
+    reminderJobs && runtime.schedulerSharedSecret
+      ? {
+          sharedSecret: runtime.schedulerSharedSecret,
+          handler: reminderJobs.handle
+        }
+      : undefined
 })
 
 if (import.meta.main) {

apps/bot/src/reminder-jobs.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import type { ReminderJobResult, ReminderJobService } from '@household/application'
+
+import { createReminderJobsHandler } from './reminder-jobs'
+
+describe('createReminderJobsHandler', () => {
+  test('returns job outcome with dedupe metadata', async () => {
+    const claimedResult: ReminderJobResult = {
+      status: 'claimed',
+      dedupeKey: '2026-03:utilities',
+      payloadHash: 'hash',
+      reminderType: 'utilities',
+      period: '2026-03',
+      messageText: 'Utilities reminder for 2026-03'
+    }
+
+    const reminderService: ReminderJobService = {
+      handleJob: mock(async () => claimedResult)
+    }
+
+    const handler = createReminderJobsHandler({
+      householdId: 'household-1',
+      reminderService
+    })
+
+    const response = await handler.handle(
+      new Request('http://localhost/jobs/reminder/utilities', {
+        method: 'POST',
+        body: JSON.stringify({
+          period: '2026-03',
+          jobId: 'job-1'
+        })
+      }),
+      'utilities'
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      jobId: 'job-1',
+      reminderType: 'utilities',
+      period: '2026-03',
+      dedupeKey: '2026-03:utilities',
+      outcome: 'claimed',
+      dryRun: false,
+      messageText: 'Utilities reminder for 2026-03'
+    })
+  })
+
+  test('supports forced dry-run mode', async () => {
+    const dryRunResult: ReminderJobResult = {
+      status: 'dry-run',
+      dedupeKey: '2026-03:rent-warning',
+      payloadHash: 'hash',
+      reminderType: 'rent-warning',
+      period: '2026-03',
+      messageText: 'Rent reminder for 2026-03: payment is coming up soon.'
+    }
+
+    const reminderService: ReminderJobService = {
+      handleJob: mock(async () => dryRunResult)
+    }
+
+    const handler = createReminderJobsHandler({
+      householdId: 'household-1',
+      reminderService,
+      forceDryRun: true
+    })
+
+    const response = await handler.handle(
+      new Request('http://localhost/jobs/reminder/rent-warning', {
+        method: 'POST',
+        body: JSON.stringify({ period: '2026-03', jobId: 'job-2' })
+      }),
+      'rent-warning'
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toMatchObject({
+      outcome: 'dry-run',
+      dryRun: true
+    })
+  })
+
+  test('rejects unsupported reminder type', async () => {
+    const handler = createReminderJobsHandler({
+      householdId: 'household-1',
+      reminderService: {
+        handleJob: mock(async () => {
+          throw new Error('should not be called')
+        })
+      }
+    })
+
+    const response = await handler.handle(
+      new Request('http://localhost/jobs/reminder/unknown', {
+        method: 'POST',
+        body: JSON.stringify({ period: '2026-03' })
+      }),
+      'unknown'
+    )
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toEqual({
+      ok: false,
+      error: 'Invalid reminder type'
+    })
+  })
+})

apps/bot/src/reminder-jobs.ts

@@ -0,0 +1,111 @@
+import { BillingPeriod } from '@household/domain'
+import type { ReminderJobService } from '@household/application'
+
+const REMINDER_TYPES = ['utilities', 'rent-warning', 'rent-due'] as const
+type ReminderType = (typeof REMINDER_TYPES)[number]
+
+interface ReminderJobRequestBody {
+  period?: string
+  jobId?: string
+  dryRun?: boolean
+}
+
+function json(body: object, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      'content-type': 'application/json; charset=utf-8'
+    }
+  })
+}
+
+function parseReminderType(raw: string): ReminderType | null {
+  if ((REMINDER_TYPES as readonly string[]).includes(raw)) {
+    return raw as ReminderType
+  }
+
+  return null
+}
+
+function currentPeriod(): string {
+  const now = new Date()
+  const year = now.getUTCFullYear()
+  const month = `${now.getUTCMonth() + 1}`.padStart(2, '0')
+
+  return `${year}-${month}`
+}
+
+async function readBody(request: Request): Promise<ReminderJobRequestBody> {
+  const text = await request.text()
+
+  if (text.trim().length === 0) {
+    return {}
+  }
+
+  const parsed = JSON.parse(text) as ReminderJobRequestBody
+  return parsed
+}
+
+export function createReminderJobsHandler(options: {
+  householdId: string
+  reminderService: ReminderJobService
+  forceDryRun?: boolean
+}): {
+  handle: (request: Request, rawReminderType: string) => Promise<Response>
+} {
+  return {
+    handle: async (request, rawReminderType) => {
+      const reminderType = parseReminderType(rawReminderType)
+      if (!reminderType) {
+        return json({ ok: false, error: 'Invalid reminder type' }, 400)
+      }
+
+      try {
+        const body = await readBody(request)
+        const period = BillingPeriod.fromString(body.period ?? currentPeriod()).toString()
+        const dryRun = options.forceDryRun === true || body.dryRun === true
+        const result = await options.reminderService.handleJob({
+          householdId: options.householdId,
+          period,
+          reminderType,
+          dryRun
+        })
+
+        const logPayload = {
+          event: 'scheduler.reminder.dispatch',
+          reminderType,
+          period,
+          jobId: body.jobId ?? null,
+          dedupeKey: result.dedupeKey,
+          outcome: result.status,
+          dryRun
+        }
+
+        console.log(JSON.stringify(logPayload))
+
+        return json({
+          ok: true,
+          jobId: body.jobId ?? null,
+          reminderType,
+          period,
+          dedupeKey: result.dedupeKey,
+          outcome: result.status,
+          dryRun,
+          messageText: result.messageText
+        })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown reminder job error'
+
+        console.error(
+          JSON.stringify({
+            event: 'scheduler.reminder.dispatch_failed',
+            reminderType: rawReminderType,
+            error: message
+          })
+        )
+
+        return json({ ok: false, error: message }, 400)
+      }
+    }
+  }
+}

apps/bot/src/server.test.ts

@@ -6,7 +6,17 @@ describe('createBotWebhookServer', () => {
   const server = createBotWebhookServer({
     webhookPath: '/webhook/telegram',
     webhookSecret: 'secret-token',
-    webhookHandler: async () => new Response('ok', { status: 200 })
+    webhookHandler: async () => new Response('ok', { status: 200 }),
+    scheduler: {
+      sharedSecret: 'scheduler-secret',
+      handler: async (_request, reminderType) =>
+        new Response(JSON.stringify({ ok: true, reminderType }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json; charset=utf-8'
+          }
+        })
+    }
   })
 
   test('returns health payload', async () => {
@@ -59,4 +69,46 @@ describe('createBotWebhookServer', () => {
     expect(response.status).toBe(200)
     expect(await response.text()).toBe('ok')
   })
+
+  test('rejects scheduler request with missing secret', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/jobs/reminder/utilities', {
+        method: 'POST',
+        body: JSON.stringify({ period: '2026-03' })
+      })
+    )
+
+    expect(response.status).toBe(401)
+  })
+
+  test('rejects non-post method for scheduler endpoint', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/jobs/reminder/utilities', {
+        method: 'GET',
+        headers: {
+          'x-household-scheduler-secret': 'scheduler-secret'
+        }
+      })
+    )
+
+    expect(response.status).toBe(405)
+  })
+
+  test('accepts authorized scheduler request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/jobs/reminder/rent-due', {
+        method: 'POST',
+        headers: {
+          'x-household-scheduler-secret': 'scheduler-secret'
+        },
+        body: JSON.stringify({ period: '2026-03' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      reminderType: 'rent-due'
+    })
+  })
 })

apps/bot/src/server.ts

@@ -2,6 +2,13 @@ export interface BotWebhookServerOptions {
   webhookPath: string
   webhookSecret: string
   webhookHandler: (request: Request) => Promise<Response> | Response
+  scheduler?:
+    | {
+        pathPrefix?: string
+        sharedSecret: string
+        handler: (request: Request, reminderType: string) => Promise<Response>
+      }
+    | undefined
 }
 
 function json(body: object, status = 200): Response {
@@ -19,12 +26,22 @@ function isAuthorized(request: Request, expectedSecret: string): boolean {
   return secretHeader === expectedSecret
 }
 
+function isSchedulerAuthorized(request: Request, expectedSecret: string): boolean {
+  const customHeader = request.headers.get('x-household-scheduler-secret')
+  const authorizationHeader = request.headers.get('authorization')
+
+  return customHeader === expectedSecret || authorizationHeader === `Bearer ${expectedSecret}`
+}
+
 export function createBotWebhookServer(options: BotWebhookServerOptions): {
   fetch: (request: Request) => Promise<Response>
 } {
   const normalizedWebhookPath = options.webhookPath.startsWith('/')
     ? options.webhookPath
     : `/${options.webhookPath}`
+  const schedulerPathPrefix = options.scheduler
+    ? (options.scheduler.pathPrefix ?? '/jobs/reminder')
+    : null
 
   return {
     fetch: async (request: Request) => {
@@ -35,6 +52,19 @@ export function createBotWebhookServer(options: BotWebhookServerOptions): {
       }
 
       if (url.pathname !== normalizedWebhookPath) {
+        if (schedulerPathPrefix && url.pathname.startsWith(`${schedulerPathPrefix}/`)) {
+          if (request.method !== 'POST') {
+            return new Response('Method Not Allowed', { status: 405 })
+          }
+
+          if (!isSchedulerAuthorized(request, options.scheduler!.sharedSecret)) {
+            return new Response('Unauthorized', { status: 401 })
+          }
+
+          const reminderType = url.pathname.slice(`${schedulerPathPrefix}/`.length)
+          return await options.scheduler!.handler(request, reminderType)
+        }
+
         return new Response('Not Found', { status: 404 })
       }