financeops-mcp 0.1.0

package/tests/tools/financial_health.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mockBalances, mockTransactions, mockSubscriptions } from '../helpers/mock-data.js';
+
+// ─── Mock Stripe SDK ──────────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: 'usd', amount: 500000 }],
+        pending: [{ currency: 'usd', amount: 25000 }],
+      }),
+    },
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          { id: 'txn_1', created: 1743465600, amount: 20000, currency: 'usd', description: 'Revenue', type: 'charge', metadata: {} },
+          { id: 'txn_2', created: 1743552000, amount: 20000, currency: 'usd', description: 'Revenue', type: 'charge', metadata: {} },
+          { id: 'txn_3', created: 1743638400, amount: -3000, currency: 'usd', description: 'Stripe fee', type: 'stripe_fee', metadata: {} },
+        ],
+        has_more: false,
+      }),
+    },
+    invoices: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    subscriptions: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          {
+            id: 'sub_1',
+            customer: 'cus_aaa',
+            currency: 'usd',
+            status: 'active',
+            current_period_start: 1743465600,
+            current_period_end: 1746057600,
+            items: { data: [{ price: { unit_amount: 9900, recurring: { interval: 'month' } } }] },
+          },
+          {
+            id: 'sub_2',
+            customer: 'cus_bbb',
+            currency: 'usd',
+            status: 'active',
+            current_period_start: 1743465600,
+            current_period_end: 1746057600,
+            items: { data: [{ price: { unit_amount: 4900, recurring: { interval: 'month' } } }] },
+          },
+          {
+            id: 'sub_3',
+            customer: 'cus_ccc',
+            currency: 'usd',
+            status: 'canceled',
+            current_period_start: 1740787200,
+            current_period_end: 1743465600,
+            items: { data: [{ price: { unit_amount: 2900, recurring: { interval: 'month' } } }] },
+          },
+        ],
+      }),
+    },
+  }));
+  return { default: mockStripe };
+});
+
+describe('financial_health — MRR calculation', () => {
+  it('MRR is sum of active subscriptions monthly amount', () => {
+    const subscriptions = mockSubscriptions();
+    const activeSubs = subscriptions.filter((s) => s.status === 'active');
+
+    const mrr = activeSubs.reduce((sum, s) => {
+      const monthly = s.interval === 'year' ? s.amount / 12 : s.amount;
+      return sum + monthly;
+    }, 0);
+
+    // mockSubscriptions: sub_1=9900 + sub_2=2900 = 12800 cents = $128 MRR
+    expect(mrr).toBe(12800);
+    expect(mrr / 100).toBe(128);
+  });
+
+  it('MRR excludes past_due and canceled subscriptions', () => {
+    const subscriptions = mockSubscriptions();
+    const activeSubs = subscriptions.filter((s) => s.status === 'active');
+    const allSubs = subscriptions;
+
+    expect(activeSubs.length).toBeLessThan(allSubs.length);
+  });
+
+  it('annual subscriptions are normalized to monthly for MRR', () => {
+    const subscriptions = [
+      { id: 'sub_annual', customer_name: 'Big Co', amount: 120000, currency: 'usd', interval: 'year' as const, status: 'active' as const, current_period_start: '2026-01-01', current_period_end: '2027-01-01', provider: 'stripe' as const },
+    ];
+
+    const mrr = subscriptions.reduce((sum, s) => {
+      const monthly = s.interval === 'year' ? s.amount / 12 : s.amount;
+      return sum + monthly;
+    }, 0);
+
+    expect(mrr).toBe(10000);  // $100/month
+  });
+
+  it('subscriptions data fetched from Stripe adapter', async () => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const subs = await adapter.getSubscriptions!();
+
+    expect(Array.isArray(subs)).toBe(true);
+    expect(subs.length).toBeGreaterThan(0);
+  });
+});
+
+describe('financial_health — churn rate', () => {
+  it('churn rate = canceled / total * 100', () => {
+    const subscriptions = mockSubscriptions();
+    const totalSubs = subscriptions.length;
+    const canceledSubs = subscriptions.filter((s) => s.status === 'canceled').length;
+    const churnRate = totalSubs > 0 ? (canceledSubs / totalSubs) * 100 : 0;
+
+    expect(churnRate).toBe(0);  // No canceled in mock
+  });
+
+  it('churn rate is 100% when all subscriptions are canceled', () => {
+    const subscriptions = [
+      { id: 'sub_1', customer_name: 'A', amount: 9900, currency: 'usd', interval: 'month' as const, status: 'canceled' as const, current_period_start: '2026-01-01', current_period_end: '2026-02-01', provider: 'stripe' as const },
+      { id: 'sub_2', customer_name: 'B', amount: 4900, currency: 'usd', interval: 'month' as const, status: 'canceled' as const, current_period_start: '2026-01-01', current_period_end: '2026-02-01', provider: 'stripe' as const },
+    ];
+
+    const totalSubs = subscriptions.length;
+    const canceledSubs = subscriptions.filter((s) => s.status === 'canceled').length;
+    const churnRate = totalSubs > 0 ? (canceledSubs / totalSubs) * 100 : 0;
+
+    expect(churnRate).toBe(100);
+  });
+
+  it('churn rate is 0 when no subscriptions', () => {
+    const totalSubs = 0;
+    const churnRate = totalSubs > 0 ? 0 : 0;
+    expect(churnRate).toBe(0);
+  });
+
+  it('partial churn rate: 1 of 3 canceled = 33.33%', () => {
+    const subscriptions = [
+      { status: 'active' as const },
+      { status: 'active' as const },
+      { status: 'canceled' as const },
+    ];
+    const total = subscriptions.length;
+    const canceled = subscriptions.filter((s) => s.status === 'canceled').length;
+    const churnRate = (canceled / total) * 100;
+
+    expect(churnRate).toBeCloseTo(33.33, 1);
+  });
+});
+
+describe('financial_health — burn rate and runway', () => {
+  it('runway = total_balance / burn_rate (in months)', () => {
+    const totalAvailableCents = 500000;  // $5000
+    const monthlyExpensesCents = 50000;  // $500/month
+
+    const burnRate = monthlyExpensesCents / 100;  // $500
+    const totalBalance = totalAvailableCents / 100;  // $5000
+    const runwayMonths = totalBalance / burnRate;  // 10 months
+
+    expect(runwayMonths).toBe(10);
+  });
+
+  it('runway is null when burn rate is zero', () => {
+    const burnRate = 0;
+    const totalBalance = 5000;
+    const runway = burnRate > 0 ? totalBalance / burnRate : null;
+
+    expect(runway).toBeNull();
+  });
+
+  it('total balance = sum of available across all currencies', () => {
+    const balances = mockBalances('stripe');
+    const totalAvailable = balances.reduce((sum, b) => sum + b.available, 0);
+
+    expect(totalAvailable).toBe(650000);  // 500000 USD + 150000 EUR
+  });
+
+  it('monthly income > 0 from mock transactions', async () => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const txResult = await adapter.getTransactions({});
+
+    const monthlyIncome = txResult.data
+      .filter((t) => t.type === 'income')
+      .reduce((sum, t) => sum + t.amount, 0);
+
+    expect(monthlyIncome / 100).toBeGreaterThan(0);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+});

package/tests/tools/get_balances.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mockBalances } from '../helpers/mock-data.js';
+
+// ─── Mock Stripe SDK ──────────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [
+          { currency: 'usd', amount: 1000000 },
+          { currency: 'eur', amount: 250000 },
+          { currency: 'gbp', amount: 75000 },
+        ],
+        pending: [
+          { currency: 'usd', amount: 50000 },
+          { currency: 'eur', amount: 10000 },
+        ],
+      }),
+    },
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    invoices: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    subscriptions: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+    },
+  }));
+  return { default: mockStripe };
+});
+
+describe('get_balances tool — Stripe', () => {
+  beforeEach(() => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns an array of balance objects', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    expect(Array.isArray(balances)).toBe(true);
+    expect(balances.length).toBeGreaterThan(0);
+  });
+
+  it('each balance has required fields', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    for (const b of balances) {
+      expect(b).toHaveProperty('currency');
+      expect(b).toHaveProperty('available');
+      expect(b).toHaveProperty('pending');
+      expect(b).toHaveProperty('provider');
+    }
+  });
+
+  it('all balances have provider set to stripe', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    for (const b of balances) {
+      expect(b.provider).toBe('stripe');
+    }
+  });
+
+  it('USD balance available is correct in cents', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    const usd = balances.find((b) => b.currency === 'usd');
+    expect(usd).toBeDefined();
+    expect(usd!.available).toBe(1000000);
+  });
+
+  it('EUR balance is returned', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    const eur = balances.find((b) => b.currency === 'eur');
+    expect(eur).toBeDefined();
+    expect(eur!.available).toBe(250000);
+  });
+
+  it('GBP balance is returned', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    const gbp = balances.find((b) => b.currency === 'gbp');
+    expect(gbp).toBeDefined();
+    expect(gbp!.available).toBe(75000);
+  });
+
+  it('pending amount defaults to 0 for currencies with no pending', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    const gbp = balances.find((b) => b.currency === 'gbp');
+    // GBP has no pending in mock — should default to 0
+    expect(gbp!.pending).toBe(0);
+  });
+
+  it('available and pending are integers (cents)', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const balances = await adapter.getBalances();
+
+    for (const b of balances) {
+      expect(Number.isInteger(b.available)).toBe(true);
+      expect(Number.isInteger(b.pending)).toBe(true);
+    }
+  });
+});
+
+describe('get_balances — mock data helper', () => {
+  it('mockBalances returns stripe provider by default', () => {
+    const balances = mockBalances('stripe');
+    for (const b of balances) {
+      expect(b.provider).toBe('stripe');
+    }
+  });
+
+  it('mockBalances returns xero provider when specified', () => {
+    const balances = mockBalances('xero');
+    for (const b of balances) {
+      expect(b.provider).toBe('xero');
+    }
+  });
+
+  it('mockBalances returns usd and eur', () => {
+    const balances = mockBalances('stripe');
+    const currencies = balances.map((b) => b.currency);
+    expect(currencies).toContain('usd');
+    expect(currencies).toContain('eur');
+  });
+
+  it('multi-provider balance combination is additive', () => {
+    const stripeBalances = mockBalances('stripe');
+    const xeroBalances = mockBalances('xero');
+    const allBalances = [...stripeBalances, ...xeroBalances];
+
+    const stripeCount = allBalances.filter((b) => b.provider === 'stripe').length;
+    const xeroCount = allBalances.filter((b) => b.provider === 'xero').length;
+
+    expect(stripeCount).toBeGreaterThan(0);
+    expect(xeroCount).toBeGreaterThan(0);
+    expect(allBalances.length).toBe(stripeCount + xeroCount);
+  });
+});

package/tests/tools/list_invoices.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mockInvoices } from '../helpers/mock-data.js';
+
+// ─── Mock Stripe SDK ──────────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    invoices: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          {
+            id: 'in_001',
+            number: 'INV-001',
+            customer_name: 'Customer A',
+            customer_email: 'a@example.com',
+            amount_due: 9900,
+            currency: 'usd',
+            status: 'paid',
+            due_date: 1748736000,
+            created: 1746057600,
+            status_transitions: { paid_at: 1748044800 },
+          },
+          {
+            id: 'in_002',
+            number: 'INV-002',
+            customer_name: 'Customer B',
+            customer_email: 'b@example.com',
+            amount_due: 4900,
+            currency: 'usd',
+            status: 'open',
+            due_date: 1748822400,
+            created: 1746144000,
+            status_transitions: { paid_at: null },
+          },
+          {
+            id: 'in_003',
+            number: 'INV-003',
+            customer_name: 'Customer C',
+            customer_email: 'c@example.com',
+            amount_due: 19900,
+            currency: 'usd',
+            status: 'paid',
+            due_date: 1743465600,
+            created: 1740787200,
+            status_transitions: { paid_at: 1743465600 },
+          },
+        ],
+        has_more: false,
+      }),
+    },
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: 'usd', amount: 500000 }],
+        pending: [],
+      }),
+    },
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    subscriptions: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+    },
+  }));
+  return { default: mockStripe };
+});
+
+describe('list_invoices tool — Stripe provider', () => {
+  beforeEach(() => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns paginated result with data array', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    expect(result).toHaveProperty('data');
+    expect(result).toHaveProperty('has_more');
+    expect(Array.isArray(result.data)).toBe(true);
+  });
+
+  it('each invoice has required fields', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    for (const inv of result.data) {
+      expect(inv).toHaveProperty('id');
+      expect(inv).toHaveProperty('number');
+      expect(inv).toHaveProperty('customer_name');
+      expect(inv).toHaveProperty('amount');
+      expect(inv).toHaveProperty('currency');
+      expect(inv).toHaveProperty('status');
+      expect(inv).toHaveProperty('provider');
+    }
+  });
+
+  it('amounts are in cents', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    for (const inv of result.data) {
+      expect(Number.isInteger(inv.amount)).toBe(true);
+    }
+  });
+
+  it('all invoices have provider set to stripe', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    for (const inv of result.data) {
+      expect(inv.provider).toBe('stripe');
+    }
+  });
+
+  it('paid invoices have paid_date set', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    const paidInvoices = result.data.filter((inv) => inv.status === 'paid');
+    expect(paidInvoices.length).toBeGreaterThan(0);
+    for (const inv of paidInvoices) {
+      expect(inv.paid_date).toBeDefined();
+    }
+  });
+
+  it('unpaid invoices do not have paid_date', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    const unpaidInvoices = result.data.filter((inv) => inv.status !== 'paid');
+    for (const inv of unpaidInvoices) {
+      expect(inv.paid_date).toBeUndefined();
+    }
+  });
+
+  it('has_more: false results in no next_cursor', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getInvoices({});
+
+    expect(result.has_more).toBe(false);
+    expect(result.next_cursor).toBeUndefined();
+  });
+});
+
+describe('list_invoices — mock data helper', () => {
+  it('mockInvoices returns correct count', () => {
+    const invoices = mockInvoices(5, 'stripe');
+    expect(invoices).toHaveLength(5);
+  });
+
+  it('mockInvoices uses deterministic amounts', () => {
+    const inv1 = mockInvoices(5, 'stripe');
+    const inv2 = mockInvoices(5, 'stripe');
+    expect(inv1.map((i) => i.amount)).toEqual(inv2.map((i) => i.amount));
+  });
+
+  it('mockInvoices has mix of paid and pending statuses', () => {
+    const invoices = mockInvoices(5, 'stripe');
+    const statuses = invoices.map((i) => i.status);
+    expect(statuses).toContain('paid');
+    expect(statuses).toContain('pending');
+  });
+
+  it('invoice numbers are sequential', () => {
+    const invoices = mockInvoices(3, 'stripe');
+    expect(invoices[0].number).toBe('INV-001');
+    expect(invoices[1].number).toBe('INV-002');
+    expect(invoices[2].number).toBe('INV-003');
+  });
+
+  it('mockInvoices xero provider sets provider field', () => {
+    const invoices = mockInvoices(3, 'xero');
+    for (const inv of invoices) {
+      expect(inv.provider).toBe('xero');
+    }
+  });
+
+  it('100 invoices from mock helper have correct length', () => {
+    const invoices = mockInvoices(100, 'xero');
+    expect(invoices).toHaveLength(100);
+  });
+});