feat(payments): add transparent balance guidance

packages/application/src/finance-command-service.test.ts

@@ -139,7 +139,7 @@ class FinanceRepositoryStub implements FinanceRepository {
     return false
   }
 
-  async updateParsedPurchase(input) {
+  async updateParsedPurchase(input: Parameters<FinanceRepository['updateParsedPurchase']>[0]) {
     this.lastUpdatedPurchaseInput = input
     return {
       id: input.purchaseId,
@@ -149,12 +149,16 @@ class FinanceRepositoryStub implements FinanceRepository {
       description: input.description,
       occurredAt: instantFromIso('2026-03-12T11:00:00.000Z'),
       splitMode: input.splitMode ?? 'equal',
-      participants: input.participants?.map((participant, index) => ({
-        id: `participant-${index + 1}`,
-        memberId: participant.memberId,
-        included: participant.included !== false,
-        shareAmountMinor: participant.shareAmountMinor
-      }))
+      ...(input.participants
+        ? {
+            participants: input.participants.map((participant, index) => ({
+              id: `participant-${index + 1}`,
+              memberId: participant.memberId,
+              included: participant.included !== false,
+              shareAmountMinor: participant.shareAmountMinor
+            }))
+          }
+        : {})
     }
   }
 

packages/application/src/index.ts

@@ -40,3 +40,4 @@ export {
   parsePaymentConfirmationMessage,
   type ParsedPaymentConfirmation
 } from './payment-confirmation-parser'
+export { buildMemberPaymentGuidance, type MemberPaymentGuidance } from './payment-guidance'

packages/application/src/miniapp-admin-service.ts

@@ -43,6 +43,7 @@ export interface MiniAppAdminService {
     householdId: string
     actorIsAdmin: boolean
     settlementCurrency?: string
+    paymentBalanceAdjustmentPolicy?: string
     rentAmountMajor?: string
     rentCurrency?: string
     rentDueDay: number
@@ -228,6 +229,20 @@ export function createMiniAppAdminService(
       const settlementCurrency = input.settlementCurrency
         ? parseCurrency(input.settlementCurrency)
         : undefined
+      const paymentBalanceAdjustmentPolicy = input.paymentBalanceAdjustmentPolicy
+        ? input.paymentBalanceAdjustmentPolicy === 'utilities' ||
+          input.paymentBalanceAdjustmentPolicy === 'rent' ||
+          input.paymentBalanceAdjustmentPolicy === 'separate'
+          ? input.paymentBalanceAdjustmentPolicy
+          : null
+        : undefined
+
+      if (paymentBalanceAdjustmentPolicy === null) {
+        return {
+          status: 'rejected',
+          reason: 'invalid_settings'
+        }
+      }
 
       if (input.rentAmountMajor && input.rentAmountMajor.trim().length > 0) {
         rentCurrency = parseCurrency(input.rentCurrency ?? 'USD')
@@ -244,6 +259,11 @@ export function createMiniAppAdminService(
               settlementCurrency
             }
           : {}),
+        ...(paymentBalanceAdjustmentPolicy
+          ? {
+              paymentBalanceAdjustmentPolicy
+            }
+          : {}),
         ...(rentAmountMinor !== undefined
           ? {
               rentAmountMinor

packages/application/src/payment-confirmation-service.ts

@@ -15,6 +15,7 @@ import {
 
 import type { FinanceCommandService } from './finance-command-service'
 import { parsePaymentConfirmationMessage } from './payment-confirmation-parser'
+import { buildMemberPaymentGuidance } from './payment-guidance'
 
 function billingPeriodLockDate(period: BillingPeriod, day: number): Temporal.PlainDate {
   const firstDay = Temporal.PlainDate.from({
@@ -284,10 +285,12 @@ export function createPaymentConfirmationService(input: {
             }
       }
 
-      const inferredAmount =
-        parsed.kind === 'rent'
-          ? memberLine.rentShare
-          : memberLine.utilityShare.add(memberLine.purchaseOffset)
+      const guidance = buildMemberPaymentGuidance({
+        kind: parsed.kind,
+        period: cycle.period,
+        memberLine,
+        settings
+      })
 
       const resolvedAmount = parsed.explicitAmount
         ? (
@@ -305,7 +308,7 @@ export function createPaymentConfirmationService(input: {
               parsed.explicitAmount
             )
           ).amount
-        : inferredAmount
+        : guidance.proposalAmount
 
       if (resolvedAmount.amountMinor <= 0n) {
         const saveResult = await input.repository.savePaymentConfirmation({

packages/application/src/payment-guidance.ts

@@ -0,0 +1,76 @@
+import { BillingPeriod, Money, Temporal } from '@household/domain'
+import type {
+  HouseholdBillingSettingsRecord,
+  HouseholdPaymentBalanceAdjustmentPolicy
+} from '@household/ports'
+
+import type { FinanceDashboardMemberLine } from './finance-command-service'
+
+export interface MemberPaymentGuidance {
+  kind: 'rent' | 'utilities'
+  adjustmentPolicy: HouseholdPaymentBalanceAdjustmentPolicy
+  baseAmount: Money
+  purchaseOffset: Money
+  proposalAmount: Money
+  totalRemaining: Money
+  reminderDate: string
+  dueDate: string
+  paymentWindowOpen: boolean
+  paymentDue: boolean
+}
+
+function cycleDate(period: string, day: number): Temporal.PlainDate {
+  const billingPeriod = BillingPeriod.fromString(period)
+  const [yearRaw, monthRaw] = billingPeriod.toString().split('-')
+  const year = Number(yearRaw)
+  const month = Number(monthRaw)
+  const yearMonth = new Temporal.PlainYearMonth(year, month)
+  const boundedDay = Math.min(Math.max(day, 1), yearMonth.daysInMonth)
+
+  return new Temporal.PlainDate(year, month, boundedDay)
+}
+
+function adjustmentApplies(
+  policy: HouseholdPaymentBalanceAdjustmentPolicy,
+  kind: 'rent' | 'utilities'
+): boolean {
+  return (policy === 'utilities' && kind === 'utilities') || (policy === 'rent' && kind === 'rent')
+}
+
+export function buildMemberPaymentGuidance(input: {
+  kind: 'rent' | 'utilities'
+  period: string
+  memberLine: FinanceDashboardMemberLine
+  settings: HouseholdBillingSettingsRecord
+  referenceInstant?: Temporal.Instant
+}): MemberPaymentGuidance {
+  const policy = input.settings.paymentBalanceAdjustmentPolicy ?? 'utilities'
+  const baseAmount =
+    input.kind === 'rent' ? input.memberLine.rentShare : input.memberLine.utilityShare
+  const purchaseOffset = input.memberLine.purchaseOffset
+  const proposalAmount = adjustmentApplies(policy, input.kind)
+    ? baseAmount.add(purchaseOffset)
+    : baseAmount
+
+  const reminderDay =
+    input.kind === 'rent' ? input.settings.rentWarningDay : input.settings.utilitiesReminderDay
+  const dueDay = input.kind === 'rent' ? input.settings.rentDueDay : input.settings.utilitiesDueDay
+  const reminderDate = cycleDate(input.period, reminderDay)
+  const dueDate = cycleDate(input.period, dueDay)
+  const localDate = (input.referenceInstant ?? Temporal.Now.instant())
+    .toZonedDateTimeISO(input.settings.timezone)
+    .toPlainDate()
+
+  return {
+    kind: input.kind,
+    adjustmentPolicy: policy,
+    baseAmount,
+    purchaseOffset,
+    proposalAmount,
+    totalRemaining: input.memberLine.remaining,
+    reminderDate: reminderDate.toString(),
+    dueDate: dueDate.toString(),
+    paymentWindowOpen: Temporal.PlainDate.compare(localDate, reminderDate) >= 0,
+    paymentDue: Temporal.PlainDate.compare(localDate, dueDate) >= 0
+  }
+}