financeops-mcp 0.1.0

package/tests/premium/reconcile.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { reconcile } from '../../src/analysis/reconciliation.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,
+  provider: 'stripe' | 'xero'
+): Transaction {
+  return {
+    id,
+    date,
+    amount,
+    currency: 'usd',
+    description,
+    type: 'income',
+    provider,
+  };
+}
+
+describe('reconcile — requirePro gate', () => {
+  it('throws ProRequiredError without license', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('reconcile')).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('reconcile')).not.toThrow();
+  });
+
+  it('HARD GATE — error message contains tool name', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    try {
+      requirePro('reconcile');
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ProRequiredError);
+      expect((err as Error).message).toContain('reconcile');
+    }
+  });
+});
+
+describe('reconcile — Stripe↔Xero matching', () => {
+  it('matches transactions with same amount, close date, similar description', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment from Acme Corp', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-01T14:00:00Z', 5000, 'Payment Acme Corp', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(1);
+    expect(result.matched[0].stripe.id).toBe('s1');
+    expect(result.matched[0].xero.id).toBe('x1');
+  });
+
+  it('HARD GATE — does not match same amount but different descriptions', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'AWS hosting fee', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-02T10:00:00Z', 5000, 'Employee lunch reimbursement', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(0);
+    expect(result.unmatched_stripe).toHaveLength(1);
+    expect(result.unmatched_xero).toHaveLength(1);
+  });
+
+  it('does not match transactions with different amounts', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-01T10:00:00Z', 5001, 'Payment Acme', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(0);
+  });
+
+  it('does not match transactions outside 2-day tolerance', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-04T10:00:00Z', 5000, 'Payment Acme Corp', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(0);
+    expect(result.unmatched_stripe).toHaveLength(1);
+    expect(result.unmatched_xero).toHaveLength(1);
+  });
+
+  it('confidence score is between 0 and 1 for matched pairs', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment from Acme', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-01T10:00:00Z', 5000, 'Payment from Acme', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched[0].confidence).toBeGreaterThanOrEqual(0);
+    expect(result.matched[0].confidence).toBeLessThanOrEqual(1);
+  });
+
+  it('summary counts are correct', () => {
+    const stripe = [
+      makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+      makeTransaction('s2', '2026-03-02T10:00:00Z', 9900, 'Subscription renewal', 'stripe'),
+    ];
+    const xero = [
+      makeTransaction('x1', '2026-03-01T14:00:00Z', 5000, 'Payment Acme Corp', 'xero'),
+      makeTransaction('x2', '2026-03-10T10:00:00Z', 9900, 'Completely different description', 'xero'),
+    ];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.summary.total_stripe).toBe(2);
+    expect(result.summary.total_xero).toBe(2);
+    expect(result.summary.matched_count).toBe(1);
+    expect(result.summary.unmatched_stripe_count).toBe(1);
+    expect(result.summary.unmatched_xero_count).toBe(1);
+  });
+
+  it('empty inputs produce empty results', () => {
+    const result = reconcile([], []);
+
+    expect(result.matched).toHaveLength(0);
+    expect(result.unmatched_stripe).toHaveLength(0);
+    expect(result.unmatched_xero).toHaveLength(0);
+    expect(result.summary.matched_count).toBe(0);
+  });
+
+  it('does not double-match the same xero transaction', () => {
+    const stripe = [
+      makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+      makeTransaction('s2', '2026-03-01T11:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+    ];
+    const xero = [
+      makeTransaction('x1', '2026-03-01T12:00:00Z', 5000, 'Payment Acme Corp', 'xero'),
+    ];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(1);
+    expect(result.unmatched_stripe).toHaveLength(1);
+  });
+
+  it('multiple matches are handled correctly', () => {
+    const stripe = [
+      makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+      makeTransaction('s2', '2026-03-05T10:00:00Z', 9900, 'Subscription BigCo', 'stripe'),
+    ];
+    const xero = [
+      makeTransaction('x1', '2026-03-01T14:00:00Z', 5000, 'Payment Acme Corp', 'xero'),
+      makeTransaction('x2', '2026-03-05T12:00:00Z', 9900, 'Subscription BigCo', 'xero'),
+    ];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(2);
+    expect(result.unmatched_stripe).toHaveLength(0);
+    expect(result.unmatched_xero).toHaveLength(0);
+  });
+});

package/tests/premium/tax_summary.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { calculateTax } from '../../src/analysis/tax.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 makeIncomeTransaction(id: string, amount: number, metadata?: Record<string, string>): Transaction {
+  return {
+    id,
+    date: '2026-03-01T00:00:00Z',
+    amount,
+    currency: 'usd',
+    description: `Sale ${id}`,
+    type: 'income',
+    provider: 'stripe',
+    metadata,
+  };
+}
+
+describe('tax_summary — requirePro gate', () => {
+  it('throws ProRequiredError without license', async () => {
+    delete process.env.PRO_LICENSE;
+    const { requirePro, ProRequiredError } = await import('../../src/premium/gate.js');
+    expect(() => requirePro('tax_summary')).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('tax_summary')).not.toThrow();
+  });
+});
+
+describe('tax_summary — tax calculation', () => {
+  it('returns TaxSummary structure with required fields', () => {
+    const transactions = [makeIncomeTransaction('t1', 10000)];
+    const result = calculateTax(transactions, 'quarter');
+
+    expect(result).toHaveProperty('provider');
+    expect(result).toHaveProperty('period');
+    expect(result).toHaveProperty('total_taxable_amount');
+    expect(result).toHaveProperty('total_tax_collected');
+    expect(result).toHaveProperty('total_tax_owed');
+    expect(result).toHaveProperty('by_rate');
+    expect(result).toHaveProperty('filing_period');
+  });
+
+  it('total_taxable_amount > 0 when there are income transactions', () => {
+    const transactions = [
+      makeIncomeTransaction('t1', 10000),
+      makeIncomeTransaction('t2', 20000),
+    ];
+
+    const result = calculateTax(transactions, 'quarter');
+    expect(result.total_taxable_amount).toBeGreaterThan(0);
+  });
+
+  it('expense transactions are excluded from tax calculation', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-03-01', amount: 50000, currency: 'usd', description: 'Expense', type: 'expense', provider: 'stripe' },
+    ];
+
+    const result = calculateTax(transactions, 'quarter');
+    expect(result.total_taxable_amount).toBe(0);
+    expect(result.total_tax_collected).toBe(0);
+    expect(result.by_rate).toHaveLength(0);
+  });
+
+  it('empty transaction list returns zeros', () => {
+    const result = calculateTax([], 'quarter');
+
+    expect(result.total_taxable_amount).toBe(0);
+    expect(result.total_tax_collected).toBe(0);
+    expect(result.total_tax_owed).toBe(0);
+    expect(result.by_rate).toHaveLength(0);
+  });
+
+  it('jurisdiction NL uses 21% standard rate', () => {
+    // Single transaction of 12100 cents = $121.00
+    // Tax-exclusive: 121 / 1.21 = 100.00 taxable, 21.00 tax
+    const transactions = [makeIncomeTransaction('t1', 12100)];
+    const result = calculateTax(transactions, 'quarter', 'NL');
+
+    expect(result.jurisdiction).toBe('NL');
+    expect(result.total_tax_collected).toBeCloseTo(21.00, 1);
+    expect(result.total_taxable_amount).toBeCloseTo(100.00, 1);
+  });
+
+  it('jurisdiction GB uses 20% standard rate', () => {
+    // 12000 cents = $120.00 inclusive
+    // Tax-exclusive: 120 / 1.20 = 100.00 taxable, 20.00 tax
+    const transactions = [makeIncomeTransaction('t1', 12000)];
+    const result = calculateTax(transactions, 'quarter', 'GB');
+
+    expect(result.jurisdiction).toBe('GB');
+    expect(result.total_tax_collected).toBeCloseTo(20.00, 1);
+  });
+
+  it('jurisdiction DE uses 19% standard rate', () => {
+    const transactions = [makeIncomeTransaction('t1', 11900)];
+    const result = calculateTax(transactions, 'quarter', 'DE');
+
+    expect(result.jurisdiction).toBe('DE');
+    expect(result.total_tax_collected).toBeCloseTo(19.00, 1);
+    expect(result.total_taxable_amount).toBeCloseTo(100.00, 1);
+  });
+
+  it('DEFAULT jurisdiction uses 20% when jurisdiction not specified', () => {
+    const transactions = [makeIncomeTransaction('t1', 12000)];
+    const result = calculateTax(transactions, 'quarter');
+
+    // Default rate = 20%
+    expect(result.total_tax_collected).toBeCloseTo(20.00, 1);
+    expect(result.jurisdiction).toBeUndefined();
+  });
+
+  it('by_rate contains entries for each rate used', () => {
+    const transactions = [makeIncomeTransaction('t1', 10000)];
+    const result = calculateTax(transactions, 'quarter');
+
+    expect(Array.isArray(result.by_rate)).toBe(true);
+    for (const entry of result.by_rate) {
+      expect(entry).toHaveProperty('rate');
+      expect(entry).toHaveProperty('rate_label');
+      expect(entry).toHaveProperty('taxable_amount');
+      expect(entry).toHaveProperty('tax_amount');
+    }
+  });
+
+  it('filing_period for quarter includes Q prefix', () => {
+    const result = calculateTax([], 'quarter');
+    expect(result.filing_period).toMatch(/^Q\d \d{4}$/);
+  });
+
+  it('filing_period for year is just the year', () => {
+    const result = calculateTax([], 'year');
+    expect(result.filing_period).toMatch(/^\d{4}$/);
+  });
+
+  it('tax metadata override: transaction with tax_rate=0 is treated as exempt', () => {
+    const transactions = [makeIncomeTransaction('t1', 10000, { tax_rate: '0' })];
+    const result = calculateTax(transactions, 'quarter');
+
+    const exemptEntry = result.by_rate.find((r) => r.rate === 0);
+    expect(exemptEntry).toBeDefined();
+    expect(exemptEntry!.rate_label).toBe('Exempt');
+  });
+
+  it('total_tax_owed equals total_tax_collected in v1', () => {
+    const transactions = [makeIncomeTransaction('t1', 12000), makeIncomeTransaction('t2', 24000)];
+    const result = calculateTax(transactions, 'year');
+
+    expect(result.total_tax_owed).toBeCloseTo(result.total_tax_collected, 5);
+  });
+});

package/tests/tools/expense_tracker.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mockExpenses } from '../helpers/mock-data.js';
+import type { 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: -500,  currency: 'usd', description: 'Stripe fee',     type: 'stripe_fee',      metadata: {} },
+          { id: 'txn_2', created: 1743552000, amount: -1500, currency: 'usd', description: 'Refund to Bob',  type: 'payment_refund',  metadata: {} },
+          { id: 'txn_3', created: 1743638400, amount: -500,  currency: 'usd', description: 'Stripe fee 2',   type: 'stripe_fee',      metadata: {} },
+          { id: 'txn_4', created: 1743724800, amount: -2000, currency: 'usd', description: 'Payout refund',  type: 'payment_refund',  metadata: {} },
+        ],
+        has_more: false,
+      }),
+    },
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: 'usd', amount: 500000 }],
+        pending: [],
+      }),
+    },
+    invoices: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    subscriptions: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+    },
+  }));
+  return { default: mockStripe };
+});
+
+describe('expense_tracker tool — Stripe adapter', () => {
+  beforeEach(() => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('expense transactions have type expense', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const expenses = result.data.filter((t) => t.type === 'expense');
+    expect(expenses.length).toBeGreaterThan(0);
+  });
+
+  it('expense amounts are in cents', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const expenses = result.data.filter((t) => t.type === 'expense');
+    for (const exp of expenses) {
+      expect(Number.isInteger(exp.amount)).toBe(true);
+    }
+  });
+});
+
+describe('expense_tracker — category grouping logic', () => {
+  it('groups expenses by category correctly', () => {
+    const expenses: Expense[] = [
+      { id: 'e1', date: '2026-03-01', amount: 5000, currency: 'usd', description: 'AWS bill', category: 'Hosting', provider: 'stripe' },
+      { id: 'e2', date: '2026-03-02', amount: 3000, currency: 'usd', description: 'Vercel', category: 'Hosting', provider: 'stripe' },
+      { id: 'e3', date: '2026-03-03', amount: 10000, currency: 'usd', description: 'Salary', category: 'Payroll', provider: 'stripe' },
+    ];
+
+    const byCategory: Record<string, number> = {};
+    for (const e of expenses) {
+      const cat = e.category ?? 'Uncategorized';
+      byCategory[cat] = (byCategory[cat] ?? 0) + e.amount;
+    }
+
+    expect(byCategory['Hosting']).toBe(8000);
+    expect(byCategory['Payroll']).toBe(10000);
+  });
+
+  it('total expenses equals sum of all categories', () => {
+    const expenses = mockExpenses(4, 'stripe');
+    const total = expenses.reduce((s, e) => s + e.amount, 0);
+
+    const byCategory: Record<string, number> = {};
+    for (const e of expenses) {
+      const cat = e.category ?? 'Uncategorized';
+      byCategory[cat] = (byCategory[cat] ?? 0) + e.amount;
+    }
+
+    const categorySum = Object.values(byCategory).reduce((s, v) => s + v, 0);
+    expect(categorySum).toBe(total);
+  });
+
+  it('total is converted to major units correctly', () => {
+    const expenses: Expense[] = [
+      { id: 'e1', date: '2026-03-01', amount: 50000, currency: 'usd', description: 'Office rent', category: 'Office', provider: 'stripe' },
+    ];
+
+    const total = expenses.reduce((s, e) => s + e.amount, 0);
+    expect(total / 100).toBe(500.00);
+  });
+
+  it('category values are converted to major units', () => {
+    const expenses: Expense[] = [
+      { id: 'e1', date: '2026-03-01', amount: 7500, currency: 'usd', description: 'AWS', category: 'Hosting', provider: 'stripe' },
+      { id: 'e2', date: '2026-03-02', amount: 2500, currency: 'usd', description: 'GCP', category: 'Hosting', provider: 'stripe' },
+    ];
+
+    const byCategory: Record<string, number> = {};
+    for (const e of expenses) {
+      const cat = e.category ?? 'Uncategorized';
+      byCategory[cat] = (byCategory[cat] ?? 0) + e.amount;
+    }
+
+    const byCategoryMajor = Object.fromEntries(
+      Object.entries(byCategory).map(([k, v]) => [k, v / 100])
+    );
+
+    expect(byCategoryMajor['Hosting']).toBe(100.00);
+  });
+
+  it('expenses without category are grouped as Uncategorized', () => {
+    const expenses: Expense[] = [
+      { id: 'e1', date: '2026-03-01', amount: 1000, currency: 'usd', description: 'Misc', category: '', provider: 'stripe' },
+    ];
+
+    const byCategory: Record<string, number> = {};
+    for (const e of expenses) {
+      const cat = e.category || 'Uncategorized';
+      byCategory[cat] = (byCategory[cat] ?? 0) + e.amount;
+    }
+
+    expect(byCategory['Uncategorized']).toBe(1000);
+  });
+
+  it('empty expenses list returns zero total', () => {
+    const expenses: Expense[] = [];
+    const total = expenses.reduce((s, e) => s + e.amount, 0);
+    expect(total / 100).toBe(0);
+  });
+
+  it('mockExpenses returns correct count', () => {
+    const expenses = mockExpenses(8, 'stripe');
+    expect(expenses).toHaveLength(8);
+  });
+
+  it('mockExpenses has multiple categories', () => {
+    const expenses = mockExpenses(8, 'stripe');
+    const categories = [...new Set(expenses.map((e) => e.category))];
+    expect(categories.length).toBeGreaterThan(1);
+  });
+
+  it('category filter: only expenses matching category are included', () => {
+    const expenses = mockExpenses(8, 'stripe');
+    const targetCategory = 'Hosting';
+
+    const filtered = expenses.filter((e) => e.category === targetCategory);
+
+    for (const exp of filtered) {
+      expect(exp.category).toBe(targetCategory);
+    }
+  });
+
+  it('expense count is tracked correctly', () => {
+    const expenses = mockExpenses(6, 'stripe');
+    expect(expenses.length).toBe(6);
+
+    const count = expenses.reduce((s) => s + 1, 0);
+    expect(count).toBe(6);
+  });
+
+  it('provider is set on all mock expenses', () => {
+    const expenses = mockExpenses(4, 'xero');
+    for (const e of expenses) {
+      expect(e.provider).toBe('xero');
+    }
+  });
+});