feat(finance): add settlement currency and cycle fx rates

packages/ports/src/exchange-rates.ts

@@ -0,0 +1,17 @@
+import type { CurrencyCode } from '@household/domain'
+
+export interface ExchangeRateQuote {
+  baseCurrency: CurrencyCode
+  quoteCurrency: CurrencyCode
+  rateMicros: bigint
+  effectiveDate: string
+  source: 'nbg'
+}
+
+export interface ExchangeRateProvider {
+  getRate(input: {
+    baseCurrency: CurrencyCode
+    quoteCurrency: CurrencyCode
+    effectiveDate: string
+  }): Promise<ExchangeRateQuote>
+}

packages/ports/src/finance.ts

@@ -14,6 +14,15 @@ export interface FinanceCycleRecord {
   currency: CurrencyCode
 }
 
+export interface FinanceCycleExchangeRateRecord {
+  cycleId: string
+  sourceCurrency: CurrencyCode
+  targetCurrency: CurrencyCode
+  rateMicros: bigint
+  effectiveDate: string
+  source: 'nbg'
+}
+
 export interface FinanceRentRuleRecord {
   amountMinor: bigint
   currency: CurrencyCode
@@ -64,6 +73,14 @@ export interface FinanceRepository {
   openCycle(period: string, currency: CurrencyCode): Promise<void>
   closeCycle(cycleId: string, closedAt: Instant): Promise<void>
   saveRentRule(period: string, amountMinor: bigint, currency: CurrencyCode): Promise<void>
+  getCycleExchangeRate(
+    cycleId: string,
+    sourceCurrency: CurrencyCode,
+    targetCurrency: CurrencyCode
+  ): Promise<FinanceCycleExchangeRateRecord | null>
+  saveCycleExchangeRate(
+    input: FinanceCycleExchangeRateRecord
+  ): Promise<FinanceCycleExchangeRateRecord>
   addUtilityBill(input: {
     cycleId: string
     billName: string

packages/ports/src/household-config.ts

@@ -51,6 +51,7 @@ export interface HouseholdMemberRecord {
 
 export interface HouseholdBillingSettingsRecord {
   householdId: string
+  settlementCurrency: CurrencyCode
   rentAmountMinor: bigint | null
   rentCurrency: CurrencyCode
   rentDueDay: number
@@ -140,6 +141,7 @@ export interface HouseholdConfigurationRepository {
   getHouseholdBillingSettings(householdId: string): Promise<HouseholdBillingSettingsRecord>
   updateHouseholdBillingSettings(input: {
     householdId: string
+    settlementCurrency?: CurrencyCode
     rentAmountMinor?: bigint | null
     rentCurrency?: CurrencyCode
     rentDueDay?: number

packages/ports/src/index.ts

@@ -30,6 +30,7 @@ export type {
 } from './anonymous-feedback'
 export type {
   FinanceCycleRecord,
+  FinanceCycleExchangeRateRecord,
   FinanceMemberRecord,
   FinanceParsedPurchaseRecord,
   FinanceRentRuleRecord,
@@ -38,6 +39,7 @@ export type {
   SettlementSnapshotLineRecord,
   SettlementSnapshotRecord
 } from './finance'
+export type { ExchangeRateProvider, ExchangeRateQuote } from './exchange-rates'
 export {
   TELEGRAM_PENDING_ACTION_TYPES,
   type TelegramPendingActionRecord,