financeops-mcp 0.1.0

package/src/adapters/xero.ts

@@ -0,0 +1,317 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import type { FinanceProvider, TransactionQuery, InvoiceQuery, ExpenseQuery } from './types.js';
+import type { Transaction, Invoice, Balance, Expense, PaginatedResult } from '../types.js';
+
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+function validateDate(date: string | undefined): string | undefined {
+  if (!date) return undefined;
+  if (!DATE_REGEX.test(date)) {
+    throw new Error(`Invalid date format: "${date}". Expected YYYY-MM-DD.`);
+  }
+  return date;
+}
+
+interface XeroTokenStore {
+  access_token: string;
+  refresh_token: string;
+  expires_at: number;  // Unix timestamp in ms
+}
+
+const TOKEN_PATH = path.join(os.homedir(), '.financeops', 'xero-tokens.json');
+
+export class XeroAdapter implements FinanceProvider {
+  private tokens: XeroTokenStore | null = null;
+  private tenantId: string;
+
+  constructor() {
+    const tenantId = process.env.XERO_TENANT_ID;
+    if (!tenantId) {
+      throw new Error('XERO_TENANT_ID environment variable is required');
+    }
+    this.tenantId = tenantId;
+    this.loadTokens();
+  }
+
+  private loadTokens(): void {
+    if (fs.existsSync(TOKEN_PATH)) {
+      try {
+        const raw = fs.readFileSync(TOKEN_PATH, 'utf-8');
+        this.tokens = JSON.parse(raw) as XeroTokenStore;
+        return;
+      } catch {
+        // Fall through to env
+      }
+    }
+
+    // Bootstrap from environment
+    const accessToken = process.env.XERO_ACCESS_TOKEN;
+    const refreshToken = process.env.XERO_REFRESH_TOKEN;
+    if (refreshToken) {
+      this.tokens = {
+        access_token: accessToken ?? '',
+        refresh_token: refreshToken,
+        expires_at: accessToken ? Date.now() + 30 * 60 * 1000 : 0,
+      };
+      this.saveTokens();
+    }
+  }
+
+  private saveTokens(): void {
+    if (!this.tokens) return;
+    const dir = path.dirname(TOKEN_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(TOKEN_PATH, JSON.stringify(this.tokens, null, 2), 'utf-8');
+  }
+
+  private async refreshAccessToken(): Promise<void> {
+    if (!this.tokens?.refresh_token) {
+      throw new Error('No Xero refresh token available. Set XERO_REFRESH_TOKEN environment variable.');
+    }
+
+    const clientId = process.env.XERO_CLIENT_ID;
+    const clientSecret = process.env.XERO_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+      throw new Error('XERO_CLIENT_ID and XERO_CLIENT_SECRET are required for token refresh');
+    }
+
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: this.tokens.refresh_token,
+    });
+
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+    const response = await fetch('https://identity.xero.com/connect/token', {
+      method: 'POST',
+      headers: {
+        Authorization: `Basic ${credentials}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Xero token refresh failed (${response.status}): ${text}`);
+    }
+
+    const data = (await response.json()) as {
+      access_token: string;
+      refresh_token: string;
+      expires_in: number;
+    };
+
+    this.tokens = {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      expires_at: Date.now() + data.expires_in * 1000,
+    };
+
+    this.saveTokens();
+  }
+
+  private async ensureFreshToken(): Promise<string> {
+    if (!this.tokens) {
+      throw new Error('No Xero tokens available. Provide XERO_REFRESH_TOKEN environment variable.');
+    }
+
+    // Refresh if within 5 minutes of expiry
+    const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+    if (!this.tokens.access_token || Date.now() >= this.tokens.expires_at - REFRESH_BUFFER_MS) {
+      await this.refreshAccessToken();
+    }
+
+    return this.tokens!.access_token;
+  }
+
+  private async request<T>(path: string): Promise<T> {
+    const token = await this.ensureFreshToken();
+
+    const response = await fetch(`https://api.xero.com/api.xro/2.0${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Xero-Tenant-Id': this.tenantId,
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Xero API error (${response.status}) for ${path}: ${text}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  async getTransactions(opts: TransactionQuery): Promise<PaginatedResult<Transaction>> {
+    validateDate(opts.date_from);
+    validateDate(opts.date_to);
+
+    const page = opts.cursor ? parseInt(opts.cursor, 10) : 1;
+    if (isNaN(page) || page < 1) {
+      throw new Error(`Invalid cursor: "${opts.cursor}". Expected a page number.`);
+    }
+
+    let queryPath = `/BankTransactions?order=Date DESC&page=${page}`;
+
+    if (opts.date_from) queryPath += `&fromDate=${opts.date_from}`;
+    if (opts.date_to) queryPath += `&toDate=${opts.date_to}`;
+
+    const data = await this.request<{ BankTransactions: any[] }>(queryPath);
+    const items = data.BankTransactions ?? [];
+
+    const transactions: Transaction[] = items.map((bt: any) => ({
+      id: bt.BankTransactionID,
+      date: bt.Date ?? '',
+      amount: Math.round((bt.Total ?? 0) * 100),  // Convert to cents
+      currency: (bt.CurrencyCode ?? 'USD').toLowerCase(),
+      description: bt.Reference ?? bt.BankTransactionID,
+      category: bt.LineItems?.[0]?.AccountCode ?? undefined,
+      type: bt.Type === 'SPEND' ? 'expense' : 'income',
+      provider: 'xero' as const,
+    }));
+
+    const XERO_PAGE_SIZE = 100;
+    const hasMore = items.length === XERO_PAGE_SIZE;
+
+    return {
+      data: transactions,
+      has_more: hasMore,
+      next_cursor: hasMore ? String(page + 1) : undefined,
+    };
+  }
+
+  async getBalances(): Promise<Balance[]> {
+    const data = await this.request<{ Accounts: any[] }>('/Accounts?where=Type=="BANK"');
+    const accounts = data.Accounts ?? [];
+
+    return accounts.map((acc: any) => ({
+      currency: (acc.CurrencyCode ?? 'USD').toLowerCase(),
+      available: Math.round((acc.Balance ?? 0) * 100),
+      pending: 0,
+      provider: 'xero' as const,
+    }));
+  }
+
+  async getInvoices(opts: InvoiceQuery): Promise<PaginatedResult<Invoice>> {
+    validateDate(opts.date_from);
+    validateDate(opts.date_to);
+
+    const page = opts.cursor ? parseInt(opts.cursor, 10) : 1;
+    if (isNaN(page) || page < 1) {
+      throw new Error(`Invalid cursor: "${opts.cursor}". Expected a page number.`);
+    }
+
+    let queryPath = `/Invoices?order=Date DESC&where=Type=="ACCREC"&page=${page}`;
+
+    if (opts.status) {
+      const statusMap: Record<string, string> = {
+        paid: 'PAID',
+        pending: 'AUTHORISED',
+        overdue: 'AUTHORISED',
+      };
+      queryPath += ` AND Status=="${statusMap[opts.status] ?? 'AUTHORISED'}"`;
+    }
+    if (opts.date_from) {
+      queryPath += ` AND Date>="${opts.date_from}"`;
+    }
+    if (opts.date_to) {
+      queryPath += ` AND Date<="${opts.date_to}"`;
+    }
+
+    const data = await this.request<{ Invoices: any[] }>(queryPath);
+
+    let invoices: Invoice[] = (data.Invoices ?? []).map((inv: any) => this.mapXeroInvoice(inv));
+
+    // Post-filter overdue
+    if (opts.status === 'overdue') {
+      const now = Date.now();
+      invoices = invoices.filter(
+        (inv) => inv.status !== 'paid' && inv.due_date && new Date(inv.due_date).getTime() < now
+      );
+    }
+
+    const XERO_PAGE_SIZE = 100;
+    const hasMore = (data.Invoices ?? []).length === XERO_PAGE_SIZE;
+
+    return {
+      data: invoices,
+      has_more: hasMore,
+      next_cursor: hasMore ? String(page + 1) : undefined,
+    };
+  }
+
+  async getExpenses(opts: ExpenseQuery): Promise<PaginatedResult<Expense>> {
+    validateDate(opts.date_from);
+    validateDate(opts.date_to);
+
+    const page = opts.cursor ? parseInt(opts.cursor, 10) : 1;
+    if (isNaN(page) || page < 1) {
+      throw new Error(`Invalid cursor: "${opts.cursor}". Expected a page number.`);
+    }
+
+    let queryPath = `/BankTransactions?order=Date DESC&where=Type=="SPEND"&page=${page}`;
+    if (opts.date_from) queryPath += `&fromDate=${opts.date_from}`;
+    if (opts.date_to) queryPath += `&toDate=${opts.date_to}`;
+
+    const data = await this.request<{ BankTransactions: any[] }>(queryPath);
+    const items = data.BankTransactions ?? [];
+
+    const expenses: Expense[] = items.map((bt: any) => ({
+      id: bt.BankTransactionID,
+      date: bt.Date ?? '',
+      amount: Math.round((bt.Total ?? 0) * 100),
+      currency: (bt.CurrencyCode ?? 'USD').toLowerCase(),
+      description: bt.Reference ?? bt.BankTransactionID,
+      category: bt.LineItems?.[0]?.AccountCode ?? 'Uncategorized',
+      provider: 'xero' as const,
+    }));
+
+    const XERO_PAGE_SIZE = 100;
+    const hasMore = items.length === XERO_PAGE_SIZE;
+
+    return {
+      data: expenses,
+      has_more: hasMore,
+      next_cursor: hasMore ? String(page + 1) : undefined,
+    };
+  }
+
+  private mapXeroInvoice(inv: any): Invoice {
+    return {
+      id: inv.InvoiceID,
+      number: inv.InvoiceNumber ?? '',
+      customer_name: inv.Contact?.Name ?? '',
+      customer_email: inv.Contact?.EmailAddress,
+      amount: Math.round((inv.Total ?? 0) * 100),  // Convert to cents
+      currency: (inv.CurrencyCode ?? 'USD').toLowerCase(),
+      status: this.mapXeroInvoiceStatus(inv.Status, inv.DueDate),
+      due_date: inv.DueDate ?? '',
+      issued_date: inv.Date ?? '',
+      paid_date: inv.FullyPaidOnDate ?? undefined,
+      provider: 'xero' as const,
+      // Read-only computed fields from Xero
+      amount_due: inv.AmountDue != null ? Math.round(inv.AmountDue * 100) : undefined,
+      amount_paid: inv.AmountPaid != null ? Math.round(inv.AmountPaid * 100) : undefined,
+      amount_credited: inv.AmountCredited != null ? Math.round(inv.AmountCredited * 100) : undefined,
+    };
+  }
+
+  private mapXeroInvoiceStatus(
+    status: string,
+    dueDate: string | undefined
+  ): 'paid' | 'pending' | 'overdue' | 'draft' | 'voided' {
+    if (status === 'PAID') return 'paid';
+    if (status === 'DRAFT') return 'draft';
+    if (status === 'VOIDED' || status === 'DELETED') return 'voided';
+    if (status === 'AUTHORISED' || status === 'SUBMITTED') {
+      if (dueDate && new Date(dueDate).getTime() < Date.now()) return 'overdue';
+      return 'pending';
+    }
+    return 'pending';
+  }
+}

package/src/analysis/anomaly.ts

@@ -0,0 +1,119 @@
+import type { Transaction, Anomaly } from '../types.js';
+
+type SensitivityLevel = 'low' | 'medium' | 'high';
+
+const VARIANCE_THRESHOLDS: Record<SensitivityLevel, number> = {
+  low: 3.0,
+  medium: 2.0,
+  high: 1.5,
+};
+
+/**
+ * Detect anomalies in a set of transactions.
+ *
+ * Rule-based detection:
+ * 1. Duplicate detection: same amount + similar description within 24 hours
+ * 2. Large variance: transaction > N×category average (N depends on sensitivity)
+ */
+export function detectAnomalies(
+  transactions: Transaction[],
+  sensitivity: SensitivityLevel = 'medium'
+): Anomaly[] {
+  const anomalies: Anomaly[] = [];
+  const threshold = VARIANCE_THRESHOLDS[sensitivity];
+
+  // --- 1. Duplicate detection ---
+  // Same amount + same provider + description similarity within 24 hours
+  for (let i = 0; i < transactions.length; i++) {
+    for (let j = i + 1; j < transactions.length; j++) {
+      const a = transactions[i];
+      const b = transactions[j];
+
+      if (a.amount !== b.amount) continue;
+      if (a.type !== b.type) continue;
+
+      const timeDiff =
+        Math.abs(new Date(a.date).getTime() - new Date(b.date).getTime()) /
+        (1000 * 60 * 60);
+
+      if (timeDiff > 24) continue;
+
+      // Description similarity: check if they share significant words
+      const descSimilar = descriptionsSimilar(a.description, b.description);
+      if (!descSimilar) continue;
+
+      anomalies.push({
+        id: `dup_${a.id}_${b.id}`,
+        type: 'duplicate',
+        severity: 'high',
+        transaction: a,
+        description: `Potential duplicate: "${a.description}" (${formatAmount(a.amount, a.currency)}) appears twice within 24 hours`,
+        amount: a.amount,
+        date: a.date,
+      });
+
+      // Only flag once per pair
+      break;
+    }
+  }
+
+  // --- 2. Large variance detection ---
+  // Group transactions by category
+  const byCategory: Record<string, Transaction[]> = {};
+  for (const t of transactions) {
+    const cat = t.category ?? 'Uncategorized';
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push(t);
+  }
+
+  for (const [category, txns] of Object.entries(byCategory)) {
+    if (txns.length < 3) continue;  // Need at least 3 to compute meaningful average
+
+    const amounts = txns.map((t) => t.amount);
+    const avg = amounts.reduce((a, b) => a + b, 0) / amounts.length;
+
+    for (const t of txns) {
+      if (avg === 0) continue;
+      const ratio = t.amount / avg;
+
+      if (ratio > threshold) {
+        anomalies.push({
+          id: `var_${t.id}`,
+          type: 'large_variance',
+          severity: ratio > threshold * 1.5 ? 'high' : 'medium',
+          transaction: t,
+          description: `Large variance in "${category}": ${formatAmount(t.amount, t.currency)} is ${ratio.toFixed(1)}× the category average of ${formatAmount(Math.round(avg), t.currency)}`,
+          amount: t.amount,
+          date: t.date,
+        });
+      }
+    }
+  }
+
+  // Deduplicate anomalies by id
+  const seen = new Set<string>();
+  return anomalies.filter((a) => {
+    if (seen.has(a.id)) return false;
+    seen.add(a.id);
+    return true;
+  });
+}
+
+function descriptionsSimilar(a: string, b: string): boolean {
+  const wordsA = new Set(a.toLowerCase().split(/\s+/).filter((w) => w.length > 2));
+  const wordsB = new Set(b.toLowerCase().split(/\s+/).filter((w) => w.length > 2));
+
+  if (wordsA.size === 0 || wordsB.size === 0) return true;  // Both empty = similar
+
+  let commonCount = 0;
+  for (const word of wordsA) {
+    if (wordsB.has(word)) commonCount++;
+  }
+
+  const jaccardSimilarity = commonCount / (wordsA.size + wordsB.size - commonCount);
+  return jaccardSimilarity >= 0.3;
+}
+
+function formatAmount(cents: number, currency: string): string {
+  return `${(cents / 100).toFixed(2)} ${currency.toUpperCase()}`;
+}

package/src/analysis/cashflow.ts

@@ -0,0 +1,158 @@
+import type { Transaction, CashFlowForecast, MonthlyForecast } from '../types.js';
+
+interface MonthlyData {
+  income: number;
+  expenses: number;
+}
+
+function getMonthKey(date: string): string {
+  return date.substring(0, 7);  // YYYY-MM
+}
+
+function addMonths(yearMonth: string, n: number): string {
+  const [year, month] = yearMonth.split('-').map(Number);
+  const d = new Date(year, month - 1 + n, 1);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+
+/**
+ * Generate a cash flow forecast using weighted moving average.
+ * 3-month lookback, 3 scenarios (conservative / realistic / optimistic ±20%).
+ * Input amounts are in cents; output is in major currency units.
+ *
+ * Spec: minimum 3 months historical data required (returns empty scenarios otherwise).
+ */
+export function forecastCashFlow(
+  transactions: Transaction[],
+  monthsAhead: number = 3
+): CashFlowForecast {
+  // Build monthly buckets from historical data
+  const monthly: Record<string, MonthlyData> = {};
+
+  for (const t of transactions) {
+    const key = getMonthKey(t.date);
+    if (!monthly[key]) monthly[key] = { income: 0, expenses: 0 };
+
+    if (t.type === 'income') {
+      monthly[key].income += t.amount / 100;
+    } else if (t.type === 'expense') {
+      monthly[key].expenses += t.amount / 100;
+    }
+  }
+
+  const sortedMonths = Object.keys(monthly).sort();
+
+  // Use last 3 months as lookback window
+  const LOOKBACK = 3;
+  const lookbackMonths = sortedMonths.slice(-LOOKBACK);
+
+  let avgIncome = 0;
+  let avgExpenses = 0;
+  let trendPct = 0;
+
+  if (lookbackMonths.length >= LOOKBACK) {
+    const windowData = lookbackMonths.map((m) => monthly[m]);
+
+    // Weighted moving average: most recent gets higher weight
+    // Weights: [1, 2, 3] for 3 months (oldest to newest)
+    const weights = [1, 2, 3];
+    const totalWeight = weights.reduce((a, b) => a + b, 0);
+
+    avgIncome =
+      windowData.reduce((sum, d, i) => sum + d.income * weights[i], 0) / totalWeight;
+    avgExpenses =
+      windowData.reduce((sum, d, i) => sum + d.expenses * weights[i], 0) / totalWeight;
+
+    // Linear trend: compare first month to last month in window
+    if (windowData.length >= 2 && windowData[0].income > 0) {
+      const firstNet = windowData[0].income - windowData[0].expenses;
+      const lastNet = windowData[windowData.length - 1].income - windowData[windowData.length - 1].expenses;
+      trendPct = firstNet !== 0 ? (lastNet - firstNet) / Math.abs(firstNet) / (windowData.length - 1) : 0;
+    }
+  }
+
+  const startMonth = sortedMonths.length > 0
+    ? addMonths(sortedMonths[sortedMonths.length - 1], 1)
+    : getMonthKey(new Date().toISOString());
+
+  const VARIANCE = 0.2;
+
+  // Conservative: -20% income
+  function buildConservative(): MonthlyForecast[] {
+    const forecasts: MonthlyForecast[] = [];
+    let cumulative = 0;
+    for (let i = 0; i < monthsAhead; i++) {
+      const month = addMonths(startMonth, i);
+      const trendMultiplier = Math.pow(1 + trendPct, i);
+      const income = avgIncome * trendMultiplier * (1 - VARIANCE);
+      const expenses = avgExpenses * trendMultiplier;
+      const net = income - expenses;
+      cumulative += net;
+      forecasts.push({
+        month,
+        income: Math.round(income * 100) / 100,
+        expenses: Math.round(expenses * 100) / 100,
+        net: Math.round(net * 100) / 100,
+        cumulative_net: Math.round(cumulative * 100) / 100,
+      });
+    }
+    return forecasts;
+  }
+
+  // Realistic: base forecast
+  function buildRealistic(): MonthlyForecast[] {
+    const forecasts: MonthlyForecast[] = [];
+    let cumulative = 0;
+    for (let i = 0; i < monthsAhead; i++) {
+      const month = addMonths(startMonth, i);
+      const trendMultiplier = Math.pow(1 + trendPct, i);
+      const income = avgIncome * trendMultiplier;
+      const expenses = avgExpenses * trendMultiplier;
+      const net = income - expenses;
+      cumulative += net;
+      forecasts.push({
+        month,
+        income: Math.round(income * 100) / 100,
+        expenses: Math.round(expenses * 100) / 100,
+        net: Math.round(net * 100) / 100,
+        cumulative_net: Math.round(cumulative * 100) / 100,
+      });
+    }
+    return forecasts;
+  }
+
+  // Optimistic: +20% income
+  function buildOptimistic(): MonthlyForecast[] {
+    const forecasts: MonthlyForecast[] = [];
+    let cumulative = 0;
+    for (let i = 0; i < monthsAhead; i++) {
+      const month = addMonths(startMonth, i);
+      const trendMultiplier = Math.pow(1 + trendPct, i);
+      const income = avgIncome * trendMultiplier * (1 + VARIANCE);
+      const expenses = avgExpenses * trendMultiplier;
+      const net = income - expenses;
+      cumulative += net;
+      forecasts.push({
+        month,
+        income: Math.round(income * 100) / 100,
+        expenses: Math.round(expenses * 100) / 100,
+        net: Math.round(net * 100) / 100,
+        cumulative_net: Math.round(cumulative * 100) / 100,
+      });
+    }
+    return forecasts;
+  }
+
+  return {
+    period_months: monthsAhead,
+    generated_at: new Date().toISOString(),
+    historical_monthly_income: Math.round(avgIncome * 100) / 100,
+    historical_monthly_expenses: Math.round(avgExpenses * 100) / 100,
+    trend_pct: Math.round(trendPct * 10000) / 10000,
+    scenarios: {
+      conservative: buildConservative(),
+      realistic: buildRealistic(),
+      optimistic: buildOptimistic(),
+    },
+  };
+}

package/src/analysis/pnl.ts

@@ -0,0 +1,80 @@
+import type { Transaction, Expense, PnLReport } from '../types.js';
+
+/**
+ * Generate a Profit & Loss report from transactions and expenses.
+ * Input amounts are in cents (smallest currency unit).
+ * Output amounts are in major currency units (e.g. 150.00).
+ */
+export function generatePnL(
+  transactions: Transaction[],
+  expenses: Expense[],
+  dateFrom: string,
+  dateTo: string
+): PnLReport {
+  // Determine currency from data (Important Fix I7)
+  const currency = transactions.length > 0 ? transactions[0].currency : 'usd';
+
+  // Revenue: income transactions in the period
+  const incomeTransactions = transactions.filter(
+    (t) =>
+      t.type === 'income' &&
+      t.date >= dateFrom &&
+      t.date <= dateTo
+  );
+
+  // Expense transactions in the period
+  const expenseTransactions = transactions.filter(
+    (t) =>
+      t.type === 'expense' &&
+      t.date >= dateFrom &&
+      t.date <= dateTo
+  );
+
+  // Direct expenses from expense records
+  const periodExpenses = expenses.filter(
+    (e) => e.date >= dateFrom && e.date <= dateTo
+  );
+
+  // Revenue in cents then convert to major units
+  const revenueCents = incomeTransactions.reduce((sum, t) => sum + t.amount, 0);
+  const revenue = revenueCents / 100;
+
+  // COGS: expense transactions (fees, refunds, direct costs)
+  const cogsCents = expenseTransactions.reduce((sum, t) => sum + t.amount, 0);
+  const cogs = cogsCents / 100;
+
+  // Operating expenses from explicit expense records
+  const opExpCents = periodExpenses.reduce((sum, e) => sum + e.amount, 0);
+  const operatingExpenses = opExpCents / 100;
+
+  const grossProfit = revenue - cogs;
+  const grossMarginPct = revenue > 0 ? (grossProfit / revenue) * 100 : 0;
+  const netIncome = grossProfit - operatingExpenses;
+
+  // Expenses by category
+  const byCategory: Record<string, number> = {};
+  for (const e of periodExpenses) {
+    const cat = e.category ?? 'Uncategorized';
+    byCategory[cat] = (byCategory[cat] ?? 0) + e.amount / 100;
+  }
+  for (const t of expenseTransactions) {
+    const cat = t.category ?? 'Other';
+    byCategory[cat] = (byCategory[cat] ?? 0) + t.amount / 100;
+  }
+
+  const period = `${dateFrom} to ${dateTo}`;
+
+  return {
+    period,
+    date_from: dateFrom,
+    date_to: dateTo,
+    currency,
+    revenue,
+    cogs,
+    gross_profit: grossProfit,
+    gross_margin_pct: Math.round(grossMarginPct * 100) / 100,
+    operating_expenses: operatingExpenses,
+    net_income: netIncome,
+    by_category: byCategory,
+  };
+}