financeops-mcp 0.1.0

package/tests/premium/detect_anomalies.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { detectAnomalies } from '../../src/analysis/anomaly.js';
+import type { Transaction } from '../../src/types.js';
+
+vi.mock('stripe', () => ({
+  default: vi.fn().mockImplementation(() => ({
+    balanceTransactions: { list: vi.fn() },
+    balance: { retrieve: vi.fn() },
+    invoices: { list: vi.fn() },
+    subscriptions: { list: vi.fn() },
+  })),
+}));
+
+afterEach(() => {
+  delete process.env.PRO_LICENSE;
+});
+
+function makeTransaction(
+  id: string,
+  date: string,
+  amount: number,
+  description: string,
+  category: string = 'Revenue',
+  type: 'income' | 'expense' | 'transfer' = 'income'
+): Transaction {
+  return { id, date, amount, currency: 'usd', description, category, type, provider: 'stripe' };
+}
+
+describe('detect_anomalies — requirePro gate', () => {
+  it('throws ProRequiredError without license', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('detect_anomalies')).toThrow(ProRequiredError);
+  });
+
+  it('does not throw with PRO_LICENSE set', async () => {
+    process.env.PRO_LICENSE = 'license-key';
+    const { requirePro } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('detect_anomalies')).not.toThrow();
+  });
+});
+
+describe('detect_anomalies — duplicate detection', () => {
+  it('detects duplicate: same amount, similar description, within 24 hours', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment from Acme'),
+      makeTransaction('t2', '2026-03-01T14:00:00Z', 5000, 'Invoice payment from Acme'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+    const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+    expect(duplicates).toHaveLength(1);
+    expect(duplicates[0].severity).toBe('high');
+  });
+
+  it('does NOT flag as duplicate if descriptions differ significantly', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'AWS hosting bill monthly'),
+      makeTransaction('t2', '2026-03-01T12:00:00Z', 5000, 'Payroll run employee A'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+    const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+    expect(duplicates).toHaveLength(0);
+  });
+
+  it('does NOT flag as duplicate if more than 24 hours apart', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+      makeTransaction('t2', '2026-03-03T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+    const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+    expect(duplicates).toHaveLength(0);
+  });
+
+  it('duplicate anomaly references the transaction', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme'),
+      makeTransaction('t2', '2026-03-01T12:00:00Z', 5000, 'Invoice payment Acme'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+    const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+    expect(duplicates[0].transaction).toBeDefined();
+  });
+});
+
+describe('detect_anomalies — variance detection', () => {
+  it('detects a spike that is significantly above category average', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01', 2000, 'Fee A', 'Fees'),
+      makeTransaction('t2', '2026-03-02', 2500, 'Fee B', 'Fees'),
+      makeTransaction('t3', '2026-03-03', 3000, 'Fee C', 'Fees'),
+      makeTransaction('t4', '2026-03-04', 3000, 'Fee D', 'Fees'),
+      makeTransaction('t5', '2026-03-05', 9000, 'Fee E (spike!)', 'Fees'),
+    ];
+
+    const anomalies = detectAnomalies(transactions, 'medium');
+    const variances = anomalies.filter((a) => a.type === 'large_variance');
+
+    expect(variances.length).toBeGreaterThan(0);
+    expect(variances[0].transaction?.id).toBe('t5');
+  });
+
+  it('medium sensitivity catches more anomalies than low sensitivity', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01', 2000, 'Fee A', 'Fees'),
+      makeTransaction('t2', '2026-03-02', 2500, 'Fee B', 'Fees'),
+      makeTransaction('t3', '2026-03-03', 2500, 'Fee C', 'Fees'),
+      makeTransaction('t4', '2026-03-04', 2500, 'Fee D', 'Fees'),
+      makeTransaction('t5', '2026-03-05', 6000, 'Fee E', 'Fees'),
+    ];
+
+    const anomaliesMedium = detectAnomalies(transactions, 'medium');
+    const anomaliesLow = detectAnomalies(transactions, 'low');
+
+    const variancesMedium = anomaliesMedium.filter((a) => a.type === 'large_variance');
+    const variancesLow = anomaliesLow.filter((a) => a.type === 'large_variance');
+
+    expect(variancesMedium.length).toBeGreaterThanOrEqual(variancesLow.length);
+  });
+
+  it('skips categories with fewer than 3 transactions', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01', 100, 'Item A', 'Rare'),
+      makeTransaction('t2', '2026-03-02', 10000, 'Item B (huge!)', 'Rare'),
+    ];
+
+    const anomalies = detectAnomalies(transactions, 'low');
+    const variances = anomalies.filter((a) => a.type === 'large_variance');
+
+    expect(variances).toHaveLength(0);
+  });
+});
+
+describe('detect_anomalies — general', () => {
+  it('returns empty array for empty input', () => {
+    const anomalies = detectAnomalies([]);
+    expect(anomalies).toHaveLength(0);
+  });
+
+  it('each anomaly has required fields: id, type, severity, description', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+      makeTransaction('t2', '2026-03-01T12:00:00Z', 5000, 'Invoice payment Acme Corp'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+
+    for (const anomaly of anomalies) {
+      expect(anomaly.id).toBeDefined();
+      expect(anomaly.type).toBeDefined();
+      expect(anomaly.severity).toBeDefined();
+      expect(anomaly.description).toBeDefined();
+    }
+  });
+
+  it('anomaly severity is one of: low, medium, high', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+      makeTransaction('t2', '2026-03-01T12:00:00Z', 5000, 'Invoice payment Acme Corp'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+
+    for (const anomaly of anomalies) {
+      expect(['low', 'medium', 'high']).toContain(anomaly.severity);
+    }
+  });
+
+  it('no anomalies when all transactions are unique and consistent', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01', 1000, 'Sale 1', 'Revenue'),
+      makeTransaction('t2', '2026-03-02', 1100, 'Sale 2', 'Revenue'),
+      makeTransaction('t3', '2026-03-03', 1050, 'Sale 3', 'Revenue'),
+    ];
+
+    const anomalies = detectAnomalies(transactions, 'low');
+    // With low sensitivity and consistent amounts, should detect few/no variances
+    const variances = anomalies.filter((a) => a.type === 'large_variance');
+    expect(variances).toHaveLength(0);
+  });
+});

package/tests/premium/gate.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { isPro, requirePro, ProRequiredError } from '../../src/premium/gate.js';
+
+afterEach(() => {
+  delete process.env.PRO_LICENSE;
+});
+
+describe('premium gate', () => {
+  it('isPro returns false when PRO_LICENSE is not set', () => {
+    delete process.env.PRO_LICENSE;
+    expect(isPro()).toBe(false);
+  });
+
+  it('isPro returns true when PRO_LICENSE is set', () => {
+    process.env.PRO_LICENSE = 'valid-license-key';
+    expect(isPro()).toBe(true);
+  });
+
+  it('requirePro throws ProRequiredError when not pro', () => {
+    delete process.env.PRO_LICENSE;
+    expect(() => requirePro('generate_pnl')).toThrow(ProRequiredError);
+    expect(() => requirePro('generate_pnl')).toThrow('generate_pnl');
+  });
+
+  it('requirePro does not throw when PRO_LICENSE is set', () => {
+    process.env.PRO_LICENSE = 'any-value';
+    expect(() => requirePro('generate_pnl')).not.toThrow();
+  });
+
+  it('reads PRO_LICENSE dynamically — responds to runtime changes', () => {
+    delete process.env.PRO_LICENSE;
+    expect(isPro()).toBe(false);
+
+    // Simulate runtime license activation
+    process.env.PRO_LICENSE = 'activated';
+    expect(isPro()).toBe(true);
+
+    // Simulate runtime license deactivation
+    delete process.env.PRO_LICENSE;
+    expect(isPro()).toBe(false);
+  });
+
+  it('error message includes the tool name', () => {
+    delete process.env.PRO_LICENSE;
+
+    try {
+      requirePro('cash_flow_forecast');
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ProRequiredError);
+      expect((err as Error).message).toContain('cash_flow_forecast');
+    }
+  });
+
+  it('PRO_LICENSE with empty string is treated as not set', () => {
+    process.env.PRO_LICENSE = '';
+    expect(isPro()).toBe(false);
+  });
+});

package/tests/premium/generate_pnl.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { generatePnL } from '../../src/analysis/pnl.js';
+import { mockTransactions, mockExpenses } from '../helpers/mock-data.js';
+import type { Transaction, Expense } from '../../src/types.js';
+
+// ─── Mock Stripe SDK ──────────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          { id: 'txn_1', created: 1743465600, amount: 50000, currency: 'usd', description: 'Revenue', type: 'charge', metadata: {} },
+          { id: 'txn_2', created: 1743552000, amount: -5000, currency: 'usd', description: 'Fee', type: 'stripe_fee', metadata: {} },
+        ],
+        has_more: false,
+      }),
+    },
+    balance: { retrieve: vi.fn() },
+    invoices: { list: vi.fn() },
+    subscriptions: { list: vi.fn() },
+  }));
+  return { default: mockStripe };
+});
+
+describe('generate_pnl — requirePro gate', () => {
+  afterEach(() => {
+    delete process.env.PRO_LICENSE;
+  });
+
+  it('throws ProRequiredError when PRO_LICENSE is not set', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('generate_pnl')).toThrow(ProRequiredError);
+  });
+
+  it('does not throw when PRO_LICENSE is set', async () => {
+    process.env.PRO_LICENSE = 'pro-license-key';
+    const { requirePro } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('generate_pnl')).not.toThrow();
+  });
+
+  it('error message mentions the tool name', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    try {
+      requirePro('generate_pnl');
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ProRequiredError);
+      expect((err as Error).message).toContain('generate_pnl');
+    }
+  });
+});
+
+describe('generate_pnl — P&L calculation', () => {
+  const dateFrom = '2026-01-01';
+  const dateTo = '2026-12-31';
+
+  it('revenue = sum of income transaction amounts (major units)', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-03-01', amount: 100000, currency: 'usd', description: 'Sale A', type: 'income', provider: 'stripe' },
+      { id: 't2', date: '2026-03-02', amount: 50000, currency: 'usd', description: 'Sale B', type: 'income', provider: 'stripe' },
+    ];
+
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+    expect(pnl.revenue).toBeCloseTo(1500.00, 2);  // 150000 cents = $1500
+  });
+
+  it('COGS = sum of expense transactions (major units)', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-03-01', amount: 10000, currency: 'usd', description: 'Fee', type: 'expense', provider: 'stripe' },
+      { id: 't2', date: '2026-03-02', amount: 5000, currency: 'usd', description: 'Fee 2', type: 'expense', provider: 'stripe' },
+    ];
+
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+    expect(pnl.cogs).toBeCloseTo(150.00, 2);  // 15000 cents = $150
+  });
+
+  it('gross_profit = revenue - COGS', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    expect(pnl.gross_profit).toBeCloseTo(pnl.revenue - pnl.cogs, 5);
+  });
+
+  it('operating_expenses = sum of Expense records (major units)', () => {
+    const expenses = mockExpenses(4, 'stripe');
+    // Amounts: 750, 1500, 2250, 3000 = 7500 cents total = $75
+    const expectedTotal = expenses.reduce((s, e) => s + e.amount, 0) / 100;
+
+    const pnl = generatePnL([], expenses, dateFrom, dateTo);
+    expect(pnl.operating_expenses).toBeCloseTo(expectedTotal, 2);
+  });
+
+  it('net_income = gross_profit - operating_expenses', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const expenses = mockExpenses(4, 'stripe');
+    const pnl = generatePnL(transactions, expenses, dateFrom, dateTo);
+
+    expect(pnl.net_income).toBeCloseTo(pnl.gross_profit - pnl.operating_expenses, 5);
+  });
+
+  it('gross_margin_pct = (gross_profit / revenue) * 100', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    const expectedMargin = pnl.revenue > 0 ? (pnl.gross_profit / pnl.revenue) * 100 : 0;
+    expect(pnl.gross_margin_pct).toBeCloseTo(expectedMargin, 1);
+  });
+
+  it('revenue is 0 for empty transaction list', () => {
+    const pnl = generatePnL([], [], dateFrom, dateTo);
+    expect(pnl.revenue).toBe(0);
+    expect(pnl.cogs).toBe(0);
+  });
+
+  it('by_category groups expenses correctly', () => {
+    const expenses = mockExpenses(8, 'stripe');
+    const pnl = generatePnL([], expenses, dateFrom, dateTo);
+
+    expect(Object.keys(pnl.by_category).length).toBeGreaterThan(0);
+  });
+
+  it('currency defaults to usd when no transactions', () => {
+    const pnl = generatePnL([], [], dateFrom, dateTo);
+    expect(pnl.currency).toBe('usd');
+  });
+
+  it('period metadata includes date_from and date_to', () => {
+    const pnl = generatePnL([], [], dateFrom, dateTo);
+    expect(pnl.date_from).toBe(dateFrom);
+    expect(pnl.date_to).toBe(dateTo);
+  });
+
+  it('multi-provider: transactions from stripe and xero are combined', () => {
+    const stripeTransactions = mockTransactions(5, 'stripe');
+    const xeroTransactions = mockTransactions(5, 'xero');
+    const allTransactions = [...stripeTransactions, ...xeroTransactions];
+
+    const pnl = generatePnL(allTransactions, [], dateFrom, dateTo);
+    const incomeCount = allTransactions.filter((t) => t.type === 'income').length;
+    expect(incomeCount).toBeGreaterThan(0);
+    expect(pnl.revenue).toBeGreaterThan(0);
+  });
+
+  it('transfer type transactions do not count as income or COGS', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-03-01', amount: 100000, currency: 'usd', description: 'Transfer', type: 'transfer', provider: 'stripe' },
+    ];
+
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+    expect(pnl.revenue).toBe(0);
+    expect(pnl.cogs).toBe(0);
+  });
+});

package/tests/premium/multi_currency_report.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import type { Balance } from '../../src/types.js';
+
+vi.mock('stripe', () => ({
+  default: vi.fn().mockImplementation(() => ({
+    balanceTransactions: { list: vi.fn() },
+    balance: { retrieve: vi.fn() },
+    invoices: { list: vi.fn() },
+    subscriptions: { list: vi.fn() },
+  })),
+}));
+
+afterEach(() => {
+  delete process.env.PRO_LICENSE;
+});
+
+// Fallback exchange rates (same as used in production when no API key)
+const FALLBACK_RATES: Record<string, Record<string, number>> = {
+  USD: { EUR: 0.92, GBP: 0.79, USD: 1.0 },
+  EUR: { USD: 1.09, GBP: 0.86, EUR: 1.0 },
+  GBP: { USD: 1.27, EUR: 1.16, GBP: 1.0 },
+};
+
+function convertCurrency(amountCents: number, from: string, to: string): number {
+  const fromUpper = from.toUpperCase();
+  const toUpper = to.toUpperCase();
+  if (fromUpper === toUpper) return amountCents;
+  const rate = FALLBACK_RATES[fromUpper]?.[toUpper];
+  if (rate === undefined) throw new Error(`No rate for ${fromUpper} → ${toUpper}`);
+  return Math.round(amountCents * rate);
+}
+
+describe('multi_currency_report — requirePro gate', () => {
+  it('throws ProRequiredError without license', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('multi_currency_report')).toThrow(ProRequiredError);
+  });
+
+  it('does not throw with PRO_LICENSE set', async () => {
+    process.env.PRO_LICENSE = 'license-key';
+    const { requirePro } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('multi_currency_report')).not.toThrow();
+  });
+
+  it('error message mentions multi_currency_report', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    try {
+      requirePro('multi_currency_report');
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ProRequiredError);
+      expect((err as Error).message).toContain('multi_currency_report');
+    }
+  });
+});
+
+describe('multi_currency_report — currency conversion with fallback rates', () => {
+  it('same currency conversion returns original amount', () => {
+    expect(convertCurrency(10000, 'USD', 'USD')).toBe(10000);
+    expect(convertCurrency(10000, 'EUR', 'EUR')).toBe(10000);
+    expect(convertCurrency(10000, 'GBP', 'GBP')).toBe(10000);
+  });
+
+  it('USD to EUR conversion uses fallback rate', () => {
+    const result = convertCurrency(10000, 'USD', 'EUR');
+    // 10000 * 0.92 = 9200
+    expect(result).toBe(9200);
+  });
+
+  it('EUR to USD conversion uses fallback rate', () => {
+    const result = convertCurrency(10000, 'EUR', 'USD');
+    // 10000 * 1.09 = 10900
+    expect(result).toBe(10900);
+  });
+
+  it('USD to GBP conversion uses fallback rate', () => {
+    const result = convertCurrency(10000, 'USD', 'GBP');
+    // 10000 * 0.79 = 7900
+    expect(result).toBe(7900);
+  });
+
+  it('GBP to USD conversion uses fallback rate', () => {
+    const result = convertCurrency(10000, 'GBP', 'USD');
+    // 10000 * 1.27 = 12700
+    expect(result).toBe(12700);
+  });
+
+  it('throws error for unsupported currency pair', () => {
+    expect(() => convertCurrency(10000, 'USD', 'JPY')).toThrow('No rate');
+  });
+
+  it('converted amounts are integers (cents)', () => {
+    const result = convertCurrency(10000, 'USD', 'EUR');
+    expect(Number.isInteger(result)).toBe(true);
+  });
+
+  it('multi-currency balance aggregation in base currency', () => {
+    const balances: Balance[] = [
+      { currency: 'usd', available: 100000, pending: 0, provider: 'stripe' },
+      { currency: 'eur', available: 50000,  pending: 0, provider: 'stripe' },
+    ];
+
+    const baseCurrency = 'USD';
+    const totalInBase = balances.reduce((sum, b) => {
+      return sum + convertCurrency(b.available, b.currency, baseCurrency);
+    }, 0);
+
+    // 100000 USD (no conversion) + 50000 EUR * 1.09 = 100000 + 54500 = 154500
+    expect(totalInBase).toBe(154500);
+  });
+
+  it('multi-provider balances from stripe and xero are combined', () => {
+    const stripeBalances: Balance[] = [
+      { currency: 'usd', available: 100000, pending: 5000, provider: 'stripe' },
+    ];
+    const xeroBalances: Balance[] = [
+      { currency: 'eur', available: 80000, pending: 0, provider: 'xero' },
+    ];
+
+    const allBalances = [...stripeBalances, ...xeroBalances];
+    expect(allBalances).toHaveLength(2);
+    expect(allBalances.some((b) => b.provider === 'stripe')).toBe(true);
+    expect(allBalances.some((b) => b.provider === 'xero')).toBe(true);
+  });
+
+  it('base_currency param in the tool schema is required', () => {
+    // Validate the schema accepts EUR, USD, GBP
+    const validCurrencies = ['EUR', 'USD', 'GBP'];
+    for (const c of validCurrencies) {
+      expect(validCurrencies).toContain(c);
+    }
+  });
+
+  it('tool returns error message when EXCHANGERATE_API_KEY is missing', () => {
+    // The current implementation returns a placeholder message when no API key
+    const message = 'multi_currency_report requires EXCHANGERATE_API_KEY. See docs.';
+    expect(message).toContain('EXCHANGERATE_API_KEY');
+  });
+});