financeops-mcp 0.1.0

package/tests/helpers/mock-data.ts

@@ -0,0 +1,135 @@
+import type {
+  Transaction,
+  Invoice,
+  Expense,
+  Balance,
+  Subscription,
+} from '../../src/adapters/types.js';
+
+/**
+ * Deterministic seed-based value generator.
+ * Returns the same sequence every time for the same seed.
+ */
+function seededValues(count: number, base: number, step: number): number[] {
+  return Array.from({ length: count }, (_, i) => base + i * step);
+}
+
+export function mockTransactions(
+  count: number = 10,
+  provider: 'stripe' | 'xero' = 'stripe'
+): Transaction[] {
+  const types: Transaction['type'][] = ['income', 'expense', 'transfer'];
+  const categories = ['Revenue', 'Refunds', 'Fees'];
+  // Deterministic amounts: 1500, 2200, 2900, 3600, 4300, 5000, 5700, 6400, 7100, 7800
+  const amounts = seededValues(count, 1500, 700);
+
+  return Array.from({ length: count }, (_, i) => ({
+    id: `txn_${provider}_${i}`,
+    date: new Date(2026, 2, 1 + i).toISOString(),  // March 2026
+    amount: amounts[i],
+    currency: 'usd',
+    description: `${provider} transaction ${i}`,
+    category: categories[i % 3],
+    type: types[i % 3],
+    provider,
+  }));
+}
+
+export function mockInvoices(
+  count: number = 5,
+  provider: 'stripe' | 'xero' = 'stripe'
+): Invoice[] {
+  const statuses: Invoice['status'][] = ['paid', 'pending', 'overdue', 'paid', 'pending'];
+  // Deterministic amounts: 5000, 10000, 15000, 20000, 25000
+  const amounts = seededValues(count, 5000, 5000);
+
+  return Array.from({ length: count }, (_, i) => ({
+    id: `inv_${provider}_${i}`,
+    number: `INV-${String(i + 1).padStart(3, '0')}`,
+    customer_name: `Customer ${i + 1}`,
+    customer_email: `customer${i + 1}@example.com`,
+    amount: amounts[i],
+    currency: 'usd',
+    status: statuses[i % statuses.length],
+    due_date: new Date(2026, 3, 10 + i).toISOString(),
+    issued_date: new Date(2026, 2, 10 + i).toISOString(),
+    paid_date:
+      statuses[i % statuses.length] === 'paid'
+        ? new Date(2026, 3, 5 + i).toISOString()
+        : undefined,
+    provider,
+  }));
+}
+
+export function mockExpenses(
+  count: number = 8,
+  provider: 'stripe' | 'xero' = 'stripe'
+): Expense[] {
+  const categories = [
+    'Processing Fees',
+    'Refunds',
+    'Office',
+    'Software',
+    'Travel',
+    'Marketing',
+    'Hosting',
+    'Payroll',
+  ];
+  // Deterministic amounts: 750, 1500, 2250, 3000, 3750, 4500, 5250, 6000
+  const amounts = seededValues(count, 750, 750);
+
+  return Array.from({ length: count }, (_, i) => ({
+    id: `exp_${provider}_${i}`,
+    date: new Date(2026, 2, 1 + i * 3).toISOString(),
+    amount: amounts[i],
+    currency: 'usd',
+    description: `${categories[i % categories.length]} expense`,
+    category: categories[i % categories.length],
+    provider,
+  }));
+}
+
+export function mockBalances(provider: 'stripe' | 'xero' = 'stripe'): Balance[] {
+  return [
+    { currency: 'usd', available: 500000, pending: 25000, provider },
+    { currency: 'eur', available: 150000, pending: 0, provider },
+  ];
+}
+
+export function mockSubscriptions(): Subscription[] {
+  return [
+    {
+      id: 'sub_1',
+      customer_name: 'Enterprise Client',
+      amount: 9900,
+      currency: 'usd',
+      interval: 'month',
+      status: 'active',
+      current_period_start: '2026-03-01T00:00:00Z',
+      current_period_end: '2026-04-01T00:00:00Z',
+      provider: 'stripe',
+    },
+    {
+      id: 'sub_2',
+      customer_name: 'Startup Co',
+      amount: 2900,
+      currency: 'usd',
+      interval: 'month',
+      status: 'active',
+      current_period_start: '2026-03-15T00:00:00Z',
+      current_period_end: '2026-04-15T00:00:00Z',
+      provider: 'stripe',
+    },
+    {
+      id: 'sub_3',
+      customer_name: 'Agency Ltd',
+      amount: 14900,
+      currency: 'usd',
+      interval: 'month',
+      status: 'past_due',
+      current_period_start: '2026-02-01T00:00:00Z',
+      current_period_end: '2026-03-01T00:00:00Z',
+      provider: 'stripe',
+    },
+  ];
+}

package/tests/lib/audit.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { logAudit, getAuditLog, cleanup, resetAuditDb } from '../../src/lib/audit.js';
+
+const TEST_DB_PATH = path.join(os.homedir(), '.financeops', 'audit-test.db');
+
+afterEach(() => {
+  resetAuditDb();
+  if (fs.existsSync(TEST_DB_PATH)) {
+    fs.unlinkSync(TEST_DB_PATH);
+  }
+});
+
+describe('audit trail', () => {
+  it('logs an audit entry', () => {
+    logAudit(
+      {
+        tool: 'list_transactions',
+        provider: 'stripe',
+        input_summary: '{ limit: 10 }',
+        success: true,
+      },
+      TEST_DB_PATH
+    );
+
+    const log = getAuditLog(10, TEST_DB_PATH);
+    expect(log).toHaveLength(1);
+    expect(log[0].tool).toBe('list_transactions');
+    expect(log[0].provider).toBe('stripe');
+  });
+
+  it('logs failed entries with error message', () => {
+    logAudit(
+      {
+        tool: 'get_balances',
+        provider: 'xero',
+        success: false,
+        error: 'Token expired',
+      },
+      TEST_DB_PATH
+    );
+
+    const log = getAuditLog(10, TEST_DB_PATH);
+    expect(log[0].error).toBe('Token expired');
+  });
+
+  it('returns most recent entries first', () => {
+    logAudit({ tool: 'tool_a', success: true }, TEST_DB_PATH);
+    logAudit({ tool: 'tool_b', success: true }, TEST_DB_PATH);
+    logAudit({ tool: 'tool_c', success: true }, TEST_DB_PATH);
+
+    const log = getAuditLog(10, TEST_DB_PATH);
+    expect(log[0].tool).toBe('tool_c');
+    expect(log[2].tool).toBe('tool_a');
+  });
+
+  it('respects the limit parameter', () => {
+    for (let i = 0; i < 10; i++) {
+      logAudit({ tool: `tool_${i}`, success: true }, TEST_DB_PATH);
+    }
+
+    const log = getAuditLog(5, TEST_DB_PATH);
+    expect(log).toHaveLength(5);
+  });
+
+  it('cleanup removes entries older than maxAgeDays', () => {
+    // We can't easily insert old entries in SQLite with 'now' default,
+    // so we verify cleanup runs without error and doesn't remove fresh entries.
+    logAudit({ tool: 'fresh_entry', success: true }, TEST_DB_PATH);
+
+    cleanup(90, TEST_DB_PATH);
+
+    const log = getAuditLog(10, TEST_DB_PATH);
+    expect(log).toHaveLength(1);  // Fresh entry survives
+    expect(log[0].tool).toBe('fresh_entry');
+  });
+
+  it('handles multiple providers in the same session', () => {
+    logAudit({ tool: 'list_transactions', provider: 'stripe', success: true }, TEST_DB_PATH);
+    logAudit({ tool: 'list_transactions', provider: 'xero', success: true }, TEST_DB_PATH);
+
+    const log = getAuditLog(10, TEST_DB_PATH);
+    expect(log).toHaveLength(2);
+    expect(log.map((e) => e.provider)).toContain('stripe');
+    expect(log.map((e) => e.provider)).toContain('xero');
+  });
+});

package/tests/lib/providers.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ─── Mock Stripe SDK ──────────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balanceTransactions: { list: vi.fn() },
+    balance: { retrieve: vi.fn() },
+    invoices: { list: vi.fn() },
+    subscriptions: { list: vi.fn() },
+  }));
+  return { default: mockStripe };
+});
+
+describe('providers — caching', () => {
+  beforeEach(async () => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+    process.env.XERO_TENANT_ID = 'tenant_test';
+    process.env.XERO_CLIENT_ID = 'client_id_test';
+    process.env.XERO_CLIENT_SECRET = 'client_secret_test';
+    process.env.XERO_REFRESH_TOKEN = 'refresh_token_test';
+
+    const { clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('getProvider returns same instance on second call (cache hit)', async () => {
+    const { getProvider, clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();
+
+    const p1 = getProvider('stripe');
+    const p2 = getProvider('stripe');
+
+    expect(p1).toBe(p2);  // Strict reference equality
+  });
+
+  it('getProvider creates fresh instance after clearProviderCache', async () => {
+    const { getProvider, clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();
+
+    const p1 = getProvider('stripe');
+    clearProviderCache();
+    const p2 = getProvider('stripe');
+
+    // After cache clear, new instance is created
+    expect(p1).not.toBe(p2);
+  });
+
+  it('getProvider returns different instances for stripe vs xero', async () => {
+    const { getProvider, clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();
+
+    const stripe = getProvider('stripe');
+    const xero = getProvider('xero');
+
+    expect(stripe).not.toBe(xero);
+  });
+
+  it('getProvider stripe instance has getTransactions method', async () => {
+    const { getProvider } = await import('../../src/lib/providers.js');
+    const provider = getProvider('stripe');
+
+    expect(typeof provider.getTransactions).toBe('function');
+  });
+
+  it('getProvider stripe instance has getBalances method', async () => {
+    const { getProvider } = await import('../../src/lib/providers.js');
+    const provider = getProvider('stripe');
+
+    expect(typeof provider.getBalances).toBe('function');
+  });
+
+  it('getProvider stripe instance has getInvoices method', async () => {
+    const { getProvider } = await import('../../src/lib/providers.js');
+    const provider = getProvider('stripe');
+
+    expect(typeof provider.getInvoices).toBe('function');
+  });
+
+  it('getProvider stripe instance has getExpenses method', async () => {
+    const { getProvider } = await import('../../src/lib/providers.js');
+    const provider = getProvider('stripe');
+
+    expect(typeof provider.getExpenses).toBe('function');
+  });
+
+  it('getProvider stripe instance has getSubscriptions method', async () => {
+    const { getProvider } = await import('../../src/lib/providers.js');
+    const provider = getProvider('stripe');
+
+    expect(typeof provider.getSubscriptions).toBe('function');
+  });
+
+  it('getProviders returns array of providers for multiple names', async () => {
+    const { getProviders, clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();
+
+    const providers = getProviders(['stripe', 'xero']);
+
+    expect(providers).toHaveLength(2);
+  });
+
+  it('getProviders returns cached instances', async () => {
+    const { getProvider, getProviders, clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();
+
+    const stripe = getProvider('stripe');
+    const providers = getProviders(['stripe']);
+
+    // The instance returned by getProviders should be the same cached one
+    expect(providers[0]).toBe(stripe);
+  });
+
+  it('clearProviderCache does not throw when cache is empty', async () => {
+    const { clearProviderCache } = await import('../../src/lib/providers.js');
+    clearProviderCache();  // First clear
+    expect(() => clearProviderCache()).not.toThrow();  // Second clear on empty cache
+  });
+
+  it('xero provider instance has getTransactions method', async () => {
+    const { getProvider } = await import('../../src/lib/providers.js');
+    const provider = getProvider('xero');
+
+    expect(typeof provider.getTransactions).toBe('function');
+  });
+});

package/tests/premium/cash_flow_forecast.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { forecastCashFlow } from '../../src/analysis/cashflow.js';
+import type { Transaction } from '../../src/types.js';
+
+// ─── Mock Stripe SDK (not needed for pure analysis tests, but avoids import errors) ──
+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;
+});
+
+describe('cash_flow_forecast — requirePro gate', () => {
+  it('throws ProRequiredError when not pro', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('cash_flow_forecast')).toThrow(ProRequiredError);
+  });
+
+  it('does not throw when PRO_LICENSE is set', async () => {
+    process.env.PRO_LICENSE = 'pro-key';
+    const { requirePro } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('cash_flow_forecast')).not.toThrow();
+  });
+});
+
+describe('cash_flow_forecast — 3 scenarios', () => {
+  const historicalTransactions: Transaction[] = [
+    { id: 'jan-inc', date: '2026-01-15', amount: 10000, currency: 'usd', description: 'Jan income', type: 'income', provider: 'stripe' },
+    { id: 'jan-exp', date: '2026-01-20', amount: 5000,  currency: 'usd', description: 'Jan expense', type: 'expense', provider: 'stripe' },
+    { id: 'feb-inc', date: '2026-02-15', amount: 12000, currency: 'usd', description: 'Feb income', type: 'income', provider: 'stripe' },
+    { id: 'feb-exp', date: '2026-02-20', amount: 6000,  currency: 'usd', description: 'Feb expense', type: 'expense', provider: 'stripe' },
+    { id: 'mar-inc', date: '2026-03-15', amount: 14000, currency: 'usd', description: 'Mar income', type: 'income', provider: 'stripe' },
+    { id: 'mar-exp', date: '2026-03-20', amount: 7000,  currency: 'usd', description: 'Mar expense', type: 'expense', provider: 'stripe' },
+  ];
+
+  it('returns conservative, realistic, and optimistic scenarios', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    expect(forecast.scenarios.conservative).toBeDefined();
+    expect(forecast.scenarios.realistic).toBeDefined();
+    expect(forecast.scenarios.optimistic).toBeDefined();
+  });
+
+  it('each scenario has correct month count (3)', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    expect(forecast.scenarios.conservative).toHaveLength(3);
+    expect(forecast.scenarios.realistic).toHaveLength(3);
+    expect(forecast.scenarios.optimistic).toHaveLength(3);
+  });
+
+  it('each scenario has correct month count (6)', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 6);
+
+    expect(forecast.scenarios.conservative).toHaveLength(6);
+    expect(forecast.scenarios.realistic).toHaveLength(6);
+    expect(forecast.scenarios.optimistic).toHaveLength(6);
+  });
+
+  it('each scenario has correct month count (12)', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 12);
+
+    expect(forecast.scenarios.conservative).toHaveLength(12);
+    expect(forecast.scenarios.realistic).toHaveLength(12);
+    expect(forecast.scenarios.optimistic).toHaveLength(12);
+  });
+
+  it('optimistic income > realistic income each month', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    for (let i = 0; i < 3; i++) {
+      expect(forecast.scenarios.optimistic[i].income).toBeGreaterThan(
+        forecast.scenarios.realistic[i].income
+      );
+    }
+  });
+
+  it('conservative income < realistic income each month', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    for (let i = 0; i < 3; i++) {
+      expect(forecast.scenarios.conservative[i].income).toBeLessThan(
+        forecast.scenarios.realistic[i].income
+      );
+    }
+  });
+
+  it('month labels are in YYYY-MM format', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+    const months = forecast.scenarios.realistic.map((m) => m.month);
+
+    for (const month of months) {
+      expect(month).toMatch(/^\d{4}-\d{2}$/);
+    }
+  });
+
+  it('cumulative_net is running total of net values', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+    const realistic = forecast.scenarios.realistic;
+
+    let running = 0;
+    for (const month of realistic) {
+      running += month.net;
+      expect(month.cumulative_net).toBeCloseTo(running, 1);
+    }
+  });
+
+  it('historical_monthly_income is > 0 for non-empty input', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+    expect(forecast.historical_monthly_income).toBeGreaterThan(0);
+  });
+
+  it('historical_monthly_expenses is > 0 for non-empty input', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+    expect(forecast.historical_monthly_expenses).toBeGreaterThan(0);
+  });
+
+  it('empty historical data returns 0 averages', () => {
+    const forecast = forecastCashFlow([], 3);
+
+    expect(forecast.historical_monthly_income).toBe(0);
+    expect(forecast.historical_monthly_expenses).toBe(0);
+  });
+
+  it('each month has income, expenses, net, cumulative_net fields', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    for (const month of forecast.scenarios.realistic) {
+      expect(month).toHaveProperty('month');
+      expect(month).toHaveProperty('income');
+      expect(month).toHaveProperty('expenses');
+      expect(month).toHaveProperty('net');
+      expect(month).toHaveProperty('cumulative_net');
+    }
+  });
+
+  it('period_months matches the requested months_ahead', () => {
+    const forecast6 = forecastCashFlow(historicalTransactions, 6);
+    expect(forecast6.period_months).toBe(6);
+
+    const forecast12 = forecastCashFlow(historicalTransactions, 12);
+    expect(forecast12.period_months).toBe(12);
+  });
+
+  it('generated_at is a valid ISO timestamp', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+    const d = new Date(forecast.generated_at);
+    expect(d.toString()).not.toBe('Invalid Date');
+  });
+});