Multi-Currency Quote-to-Cash: The FX Operations Handbook for Finance Teams

// TypeScript — Multi-Currency Conversion Service
// Centralizes rate fetching, caching, and audit logging
// for all quote-to-cash operations.

interface ConversionResult {
  from: string;
  to: string;
  originalAmount: number;
  convertedAmount: number;
  exchangeRate: number;
  rateTime: string;
  rateSource: string;
  convertedAt: string;
}

interface RatePolicy {
  type: 'live' | 'locked' | 'historical';
  date?: string; // For historical lookups
  lockedRate?: number; // From a quote record
}

const API_BASE = 'https://currency-exchange.app/api';

async function fetchLiveRate(
  from: string,
  to: string,
): Promise<{ rate: number; time: string }> {
  const url = new URL(API_BASE + '/v1-get-currency-exchange-rate');
  url.searchParams.set('from', from);
  url.searchParams.set('to', to);
  url.searchParams.set('x-api-key', process.env.FX_API_KEY ?? '');

  const response = await fetch(url.toString());
  if (!response.ok) throw new Error(`API error: ${response.status}`);
  const data = await response.json();

  return { rate: data.exchangeRate, time: data.rateTime };
}

async function fetchHistoricalRate(
  from: string,
  to: string,
  date: string,
): Promise<{ rate: number; time: string }> {
  const url = new URL(API_BASE + '/v1-historical');
  url.searchParams.set('from', from);
  url.searchParams.set('to', to);
  url.searchParams.set('date', date);
  url.searchParams.set('x-api-key', process.env.FX_API_KEY ?? '');

  const response = await fetch(url.toString());
  if (!response.ok) throw new Error(`API error: ${response.status}`);
  const data = await response.json();

  return { rate: data.exchangeRate, time: data.date };
}

async function convert(
  from: string,
  to: string,
  amount: number,
  policy: RatePolicy,
): Promise<ConversionResult> {
  let rate: number;
  let rateTime: string;
  let rateSource: string;

  switch (policy.type) {
    case 'locked':
      if (!policy.lockedRate) throw new Error('No locked rate provided');
      rate = policy.lockedRate;
      rateTime = 'locked';
      rateSource = 'quote-record';
      break;
    case 'historical':
      if (!policy.date) throw new Error('No date provided for historical rate');
      const historical = await fetchHistoricalRate(from, to, policy.date);
      rate = historical.rate;
      rateTime = historical.time;
      rateSource = 'historical-api';
      break;
    case 'live':
    default:
      const live = await fetchLiveRate(from, to);
      rate = live.rate;
      rateTime = live.time;
      rateSource = 'live-api';
  }

  return {
    from,
    to,
    originalAmount: amount,
    convertedAmount: Number((amount * rate).toFixed(2)),
    exchangeRate: rate,
    rateTime,
    rateSource,
    convertedAt: new Date().toISOString(),
  };
}

// TypeScript — Invoice Reconciliation with FX Variance
// Compares invoice rate against payment settlement rate

interface InvoiceRecord {
  id: string;
  currency: string;
  baseCurrency: string;
  amount: number;
  convertedAmount: number;
  invoiceRate: number;
  invoiceDate: string;
}

interface PaymentRecord {
  invoiceId: string;
  receivedAmount: number;
  settlementRate: number;
  paymentDate: string;
}

interface ReconciliationResult {
  invoiceId: string;
  invoiceAmount: number;
  receivedAmount: number;
  fxVariance: number;
  fxVariancePercent: number;
  status: 'matched' | 'variance' | 'overdue';
}

function reconcileInvoice(
  invoice: InvoiceRecord,
  payment: PaymentRecord,
): ReconciliationResult {
  // What the customer should have paid at the invoice rate
  const expectedPayment = invoice.amount * payment.settlementRate;

  // What the customer actually paid (converted to base currency)
  const actualReceivedBase = payment.receivedAmount * payment.settlementRate;

  // FX variance: difference caused by rate movement
  const fxVariance = Number(
    (actualReceivedBase - invoice.convertedAmount).toFixed(2),
  );
  const fxVariancePercent = Number(
    ((fxVariance / invoice.convertedAmount) * 100).toFixed(4),
  );

  return {
    invoiceId: invoice.id,
    invoiceAmount: invoice.convertedAmount,
    receivedAmount: actualReceivedBase,
    fxVariance,
    fxVariancePercent,
    status: Math.abs(fxVariancePercent) < 0.1
      ? 'matched'
      : 'variance',
  };
}

// Batch reconciliation for month-end close
async function reconcileMonth(
  invoices: InvoiceRecord[],
  payments: PaymentRecord[],
  varianceThreshold = 0.5,
) {
  const results: ReconciliationResult[] = [];

  for (const invoice of invoices) {
    const payment = payments.find(
      (p) => p.invoiceId === invoice.id,
    );

    if (!payment) {
      // Overdue: no payment received
      results.push({
        invoiceId: invoice.id,
        invoiceAmount: invoice.convertedAmount,
        receivedAmount: 0,
        fxVariance: 0,
        fxVariancePercent: 0,
        status: 'overdue',
      });
      continue;
    }

    const result = reconcileInvoice(invoice, payment);
    results.push(result);

    if (result.status === 'variance') {
      console.warn(
        `Invoice ${invoice.id}: FX variance ${result.fxVariancePercent}%` +
          ` (threshold: ${varianceThreshold}%)`,
      );
    }
  }

  return results;
}