feat: implement user preferred currency and exchange rate normalization

- Added `preferredCurrency` field to user model and updated user registration to require it.
- Integrated ExchangeRate API for cross-currency transactions and normalized money formatting across the application.
- Updated transaction forms to display amounts in the user's preferred currency.
- Implemented backfill script for existing users to set preferred currency based on their first active account.
- Enhanced reports and dashboards to reflect user-specific currency preferences.
- Added unit tests for currency formatting and exchange rate fetching.
- Updated documentation to include new environment variable `EXCHANGE_RATE_API_KEY`.

Author: dmsLakmal

actions/reports.ts

@@ -1,5 +1,10 @@
 import { Types } from "mongoose";
 
+import {
+  convertMoney,
+  preferredCurrencyOrDefault,
+  roundMoney,
+} from "@/lib/currency/rates";
 import { connectToDatabase } from "@/lib/db/client";
 import { withTenantFilter } from "@/lib/tenant/getTenant";
 import { ReportFilterInput, reportFilterSchema } from "@/lib/validators/report";
@@ -80,6 +85,9 @@ export type ReportExportRow = {
   category: string;
   account: string;
   amount: number;
+  nativeAmount?: number;
+  nativeCurrency?: string;
+  exchangeRate?: number;
   notes: string;
 };
 
@@ -90,6 +98,7 @@ export type FinancialReport = {
     toDate?: string;
   };
   generatedAt: string;
+  displayCurrency: string;
   summary: ReportSummary;
   monthly: ReportBucket[];
   categories: ReportCategory[];
@@ -101,7 +110,7 @@ export type FinancialReport = {
 const outflowTypes = ["expense", "transfer_fee", "loan_repayment"] as const;
 
 function roundToCents(value: number) {
-  return Number(value.toFixed(2));
+  return roundMoney(value);
 }
 
 function monthKey(date: Date) {
@@ -167,12 +176,14 @@ function finalizeBucket(bucket: ReportBucket): ReportBucket {
 export async function getFinancialReportForTenant(
   tenantId: string,
   input: ReportFilterInput = {},
+  options: { displayCurrency?: string } = {},
 ): Promise<FinancialReport> {
   if (!tenantId) {
     throw new Error("Unauthorized: tenantId is required");
   }
 
   const filters = reportFilterSchema.parse(input);
+  const displayCurrency = preferredCurrencyOrDefault(options.displayCurrency);
 
   await connectToDatabase();
 
@@ -221,6 +232,12 @@ export async function getFinancialReportForTenant(
       },
     ]),
   );
+  const accountCurrencyById = new Map(
+    accounts.map((account) => [
+      account._id.toString(),
+      account.baseCurrency,
+    ]),
+  );
   const monthlyByKey = new Map<string, ReportBucket>();
   const categoryByKey = new Map<string, ReportCategory>();
   const accountSummaryById = new Map<string, ReportAccountSummary>(
@@ -241,11 +258,24 @@ export async function getFinancialReportForTenant(
   const summary = emptyBucket("summary");
 
   for (const transaction of transactions as ReportTransaction[]) {
-    applyTransactionToBucket(summary, transaction);
+    const accountCurrency =
+      accountCurrencyById.get(transaction.accountId.toString()) ??
+      displayCurrency;
+    const converted = await convertMoney(
+      transaction.amount,
+      accountCurrency,
+      displayCurrency,
+    );
+    const displayTransaction = {
+      ...transaction,
+      amount: converted.amount,
+    };
+
+    applyTransactionToBucket(summary, displayTransaction);
 
     const key = monthKey(new Date(transaction.date));
     const bucket = monthlyByKey.get(key) ?? emptyBucket(key);
-    applyTransactionToBucket(bucket, transaction);
+    applyTransactionToBucket(bucket, displayTransaction);
     monthlyByKey.set(key, bucket);
 
     const categoryKey = `${transaction.type}:${transaction.category}`;
@@ -255,7 +285,7 @@ export async function getFinancialReportForTenant(
       total: 0,
       count: 0,
     };
-    category.total += transaction.amount;
+    category.total += displayTransaction.amount;
     category.count += 1;
     categoryByKey.set(categoryKey, category);
 
@@ -264,24 +294,47 @@ export async function getFinancialReportForTenant(
 
     if (accountSummary) {
       if (transaction.type === "earning") {
-        accountSummary.income += transaction.amount;
-        accountSummary.netFlow += transaction.amount;
+        accountSummary.income += displayTransaction.amount;
+        accountSummary.netFlow += displayTransaction.amount;
       }
 
       if (
         outflowTypes.includes(transaction.type as (typeof outflowTypes)[number])
       ) {
-        accountSummary.outflow += transaction.amount;
-        accountSummary.netFlow -= transaction.amount;
+        accountSummary.outflow += displayTransaction.amount;
+        accountSummary.netFlow -= displayTransaction.amount;
       }
 
       if (transaction.type === "transfer") {
-        accountSummary.transferVolume += transaction.amount;
+        accountSummary.transferVolume += displayTransaction.amount;
       }
     }
   }
 
   const finalizedSummary = finalizeBucket(summary);
+  const exportRows = await Promise.all(
+    (transactions as ReportTransaction[]).map(async (transaction) => {
+      const account = accountNameById.get(transaction.accountId.toString());
+      const nativeCurrency = account?.baseCurrency ?? displayCurrency;
+      const converted = await convertMoney(
+        transaction.amount,
+        nativeCurrency,
+        displayCurrency,
+      );
+
+      return {
+        date: new Date(transaction.date).toISOString(),
+        type: transaction.type,
+        category: transaction.category,
+        account: account?.name ?? transaction.accountId.toString(),
+        amount: converted.amount,
+        nativeAmount: transaction.amount,
+        nativeCurrency,
+        exchangeRate: converted.rate,
+        notes: transaction.notes ?? "",
+      };
+    }),
+  );
 
   return {
     filters: {
@@ -290,6 +343,7 @@ export async function getFinancialReportForTenant(
       toDate: filters.toDate,
     },
     generatedAt: new Date().toISOString(),
+    displayCurrency,
     summary: {
       income: finalizedSummary.income,
       expenses: finalizedSummary.expenses,
@@ -338,27 +392,30 @@ export async function getFinancialReportForTenant(
         isClosed: loan.isClosed,
       };
     }),
-    exportRows: (transactions as ReportTransaction[]).map((transaction) => {
-      const account = accountNameById.get(transaction.accountId.toString());
-
-      return {
-        date: new Date(transaction.date).toISOString(),
-        type: transaction.type,
-        category: transaction.category,
-        account: account?.name ?? transaction.accountId.toString(),
-        amount: transaction.amount,
-        notes: transaction.notes ?? "",
-      };
-    }),
+    exportRows,
   };
 }
 
 export function reportToCsv(report: FinancialReport): string {
-  const headers = ["date", "type", "category", "account", "amount", "notes"];
+  const headers = [
+    "date",
+    "type",
+    "category",
+    "account",
+    "amount",
+    "displayCurrency",
+    "nativeAmount",
+    "nativeCurrency",
+    "exchangeRate",
+    "notes",
+  ];
   const rows = report.exportRows.map((row) =>
     headers
       .map((header) => {
-        const value = row[header as keyof ReportExportRow];
+        const value =
+          header === "displayCurrency"
+            ? report.displayCurrency
+            : row[header as keyof ReportExportRow];
         const escaped = String(value).replaceAll('"', '""');
 
         return `"${escaped}"`;

actions/transfers.ts

@@ -1,5 +1,6 @@
 import { Types } from "mongoose";
 
+import { getExchangeRate } from "@/lib/currency/rates";
 import { runInDbTransaction } from "@/lib/db/transaction";
 import { writeAuditLog } from "@/lib/security/audit";
 import { withTenantFilter } from "@/lib/tenant/getTenant";
@@ -52,13 +53,17 @@ export async function createTransferForTenant(
     const sameCurrency =
       sourceAccount.baseCurrency === destinationAccount.baseCurrency;
 
-    if (!sameCurrency && !payload.exchangeRate) {
-      throw new Error("Exchange rate is required for cross-currency transfers");
-    }
+    const exchangeRate = sameCurrency
+      ? undefined
+      : (payload.exchangeRate ??
+        (await getExchangeRate(
+          sourceAccount.baseCurrency,
+          destinationAccount.baseCurrency,
+        )));
 
     const creditedAmount = sameCurrency
       ? roundToCents(payload.amount)
-      : roundToCents(payload.amount * Number(payload.exchangeRate));
+      : roundToCents(payload.amount * Number(exchangeRate));
 
     const debitedAmount = roundToCents(payload.amount + payload.fee);
 
@@ -88,7 +93,7 @@ export async function createTransferForTenant(
       date,
       amount: roundToCents(payload.amount),
       category: "Transfer",
-      exchangeRate: payload.exchangeRate,
+      exchangeRate,
       notes: payload.notes || "Outgoing transfer",
     });
 
@@ -101,7 +106,7 @@ export async function createTransferForTenant(
       date,
       amount: creditedAmount,
       category: "Transfer",
-      exchangeRate: payload.exchangeRate,
+      exchangeRate,
       notes: payload.notes || "Incoming transfer",
     });
 

app/(admin)/admin/finance/page.tsx

@@ -2,6 +2,9 @@ import {
   getAdminFinanceSummary,
   getAdminFinanceTenantLeaderboard,
 } from '@/actions/admin';
+import { formatMoney } from '@/lib/currency/rates';
+
+const platformReportingCurrency = 'USD';
 
 export default async function AdminFinancePage() {
   const [summary, leaderboard] = await Promise.all([
@@ -16,7 +19,8 @@ export default async function AdminFinancePage() {
           Platform Finance
         </h1>
         <p className='text-sm text-slate-500 mt-1'>
-          Global transaction metrics and tenant leaderboards
+          Global transaction metrics and tenant leaderboards in USD reporting
+          currency
         </p>
       </header>
 
@@ -26,23 +30,15 @@ export default async function AdminFinancePage() {
             Total Income
           </p>
           <p className='text-3xl font-bold text-emerald-600'>
-            $
-            {summary.income.toLocaleString('en-US', {
-              minimumFractionDigits: 2,
-              maximumFractionDigits: 2,
-            })}
+            {formatMoney(summary.income, platformReportingCurrency)}
           </p>
         </div>
         <div className='card p-5'>
           <p className='text-xs font-medium text-slate-500 uppercase tracking-wider mb-2'>
             Total Expense
           </p>
           <p className='text-3xl font-bold text-rose-600'>
-            $
-            {summary.expense.toLocaleString('en-US', {
-              minimumFractionDigits: 2,
-              maximumFractionDigits: 2,
-            })}
+            {formatMoney(summary.expense, platformReportingCurrency)}
           </p>
         </div>
         <div className='card p-5'>
@@ -52,23 +48,16 @@ export default async function AdminFinancePage() {
           <p
             className={`text-3xl font-bold ${summary.netFlow >= 0 ? 'text-emerald-600' : 'text-rose-600'}`}
           >
-            {summary.netFlow >= 0 ? '+' : ''}$
-            {summary.netFlow.toLocaleString('en-US', {
-              minimumFractionDigits: 2,
-              maximumFractionDigits: 2,
-            })}
+            {summary.netFlow >= 0 ? '+' : ''}
+            {formatMoney(summary.netFlow, platformReportingCurrency)}
           </p>
         </div>
         <div className='card p-5'>
           <p className='text-xs font-medium text-slate-500 uppercase tracking-wider mb-2'>
             Transaction Vol
           </p>
           <p className='text-3xl font-bold text-slate-900'>
-            $
-            {summary.volume.toLocaleString('en-US', {
-              minimumFractionDigits: 2,
-              maximumFractionDigits: 2,
-            })}
+            {formatMoney(summary.volume, platformReportingCurrency)}
           </p>
         </div>
       </section>
@@ -113,38 +102,23 @@ export default async function AdminFinancePage() {
                     {row.tenantId}
                   </td>
                   <td className='px-6 py-4 text-right text-emerald-600'>
-                    $
-                    {row.income.toLocaleString('en-US', {
-                      minimumFractionDigits: 2,
-                      maximumFractionDigits: 2,
-                    })}
+                    {formatMoney(row.income, platformReportingCurrency)}
                   </td>
                   <td className='px-6 py-4 text-right text-rose-600'>
-                    $
-                    {row.expense.toLocaleString('en-US', {
-                      minimumFractionDigits: 2,
-                      maximumFractionDigits: 2,
-                    })}
+                    {formatMoney(row.expense, platformReportingCurrency)}
                   </td>
                   <td className='px-6 py-4 text-right font-medium'>
                     <span
                       className={
                         row.netFlow >= 0 ? 'text-emerald-600' : 'text-rose-600'
                       }
                     >
-                      {row.netFlow >= 0 ? '+' : ''}$
-                      {row.netFlow.toLocaleString('en-US', {
-                        minimumFractionDigits: 2,
-                        maximumFractionDigits: 2,
-                      })}
+                      {row.netFlow >= 0 ? '+' : ''}
+                      {formatMoney(row.netFlow, platformReportingCurrency)}
                     </span>
                   </td>
                   <td className='px-6 py-4 text-right text-slate-600'>
-                    $
-                    {row.volume.toLocaleString('en-US', {
-                      minimumFractionDigits: 2,
-                      maximumFractionDigits: 2,
-                    })}
+                    {formatMoney(row.volume, platformReportingCurrency)}
                   </td>
                 </tr>
               ))}