financeops-mcp 0.1.0

package/tests/tools/list_transactions.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { mockTransactions } from '../helpers/mock-data.js';
+
+// ─── Mock the Stripe SDK ───────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          {
+            id: 'txn_001',
+            created: 1743465600,
+            amount: 10000,
+            currency: 'usd',
+            description: 'Payment from customer A',
+            type: 'charge',
+            metadata: {},
+          },
+          {
+            id: 'txn_002',
+            created: 1743552000,
+            amount: 5000,
+            currency: 'usd',
+            description: 'Payment from customer B',
+            type: 'charge',
+            metadata: {},
+          },
+          {
+            id: 'txn_003',
+            created: 1743638400,
+            amount: -500,
+            currency: 'usd',
+            description: 'Stripe fee',
+            type: 'stripe_fee',
+            metadata: {},
+          },
+        ],
+        has_more: false,
+      }),
+    },
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: 'usd', amount: 500000 }],
+        pending: [{ currency: 'usd', amount: 25000 }],
+      }),
+    },
+    invoices: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    subscriptions: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+    },
+  }));
+  return { default: mockStripe };
+});
+
+describe('list_transactions tool handler', () => {
+  beforeEach(() => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('getTransactions returns correct structure from Stripe adapter', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    expect(result).toHaveProperty('data');
+    expect(result).toHaveProperty('has_more');
+    expect(Array.isArray(result.data)).toBe(true);
+  });
+
+  it('returns transactions with required fields', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    for (const tx of result.data) {
+      expect(tx).toHaveProperty('id');
+      expect(tx).toHaveProperty('date');
+      expect(tx).toHaveProperty('amount');
+      expect(tx).toHaveProperty('currency');
+      expect(tx).toHaveProperty('description');
+      expect(tx).toHaveProperty('type');
+      expect(tx).toHaveProperty('provider');
+    }
+  });
+
+  it('all transactions have provider set to stripe', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    for (const tx of result.data) {
+      expect(tx.provider).toBe('stripe');
+    }
+  });
+
+  it('pagination: has_more false means no next cursor', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({ limit: 10 });
+
+    expect(result.has_more).toBe(false);
+    expect(result.next_cursor).toBeUndefined();
+  });
+
+  it('income type transactions have positive amounts', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const incomeTransactions = result.data.filter((t) => t.type === 'income');
+    for (const tx of incomeTransactions) {
+      expect(tx.amount).toBeGreaterThan(0);
+    }
+  });
+
+  it('amounts are in cents (integer values)', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    for (const tx of result.data) {
+      expect(Number.isInteger(tx.amount)).toBe(true);
+    }
+  });
+
+  it('date field is a valid ISO string', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    for (const tx of result.data) {
+      const d = new Date(tx.date);
+      expect(d.toString()).not.toBe('Invalid Date');
+    }
+  });
+
+  it('audit is logged after successful list_transactions', async () => {
+    const fs = await import('fs');
+    const os = await import('os');
+    const path = await import('path');
+    const TEST_DB_PATH = path.join(os.homedir(), '.financeops', 'audit-test-list-tx.db');
+
+    const { logAudit, getAuditLog, resetAuditDb } = await import('../../src/lib/audit.js');
+
+    resetAuditDb();
+    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');
+    expect(log[0].success).toBe(1);
+
+    resetAuditDb();
+    if (fs.existsSync(TEST_DB_PATH)) fs.unlinkSync(TEST_DB_PATH);
+  });
+
+  it('audit logs failed transactions with error message', async () => {
+    const fs = await import('fs');
+    const os = await import('os');
+    const path = await import('path');
+    const TEST_DB_PATH = path.join(os.homedir(), '.financeops', 'audit-test-list-tx-err.db');
+
+    const { logAudit, getAuditLog, resetAuditDb } = await import('../../src/lib/audit.js');
+
+    resetAuditDb();
+    logAudit({ tool: 'list_transactions', provider: 'stripe', success: false, error: 'Token expired' }, TEST_DB_PATH);
+
+    const log = getAuditLog(10, TEST_DB_PATH);
+    expect(log[0].success).toBe(0);
+    expect(log[0].error).toBe('Token expired');
+
+    resetAuditDb();
+    if (fs.existsSync(TEST_DB_PATH)) fs.unlinkSync(TEST_DB_PATH);
+  });
+
+  it('mock data helper produces deterministic transactions', () => {
+    const t1 = mockTransactions(5, 'stripe');
+    const t2 = mockTransactions(5, 'stripe');
+
+    expect(t1.map((t) => t.amount)).toEqual(t2.map((t) => t.amount));
+    expect(t1.map((t) => t.id)).toEqual(t2.map((t) => t.id));
+  });
+
+  it('mock transactions have all required fields', () => {
+    const transactions = mockTransactions(10, 'stripe');
+
+    for (const tx of transactions) {
+      expect(tx.id).toBeDefined();
+      expect(tx.date).toBeDefined();
+      expect(tx.amount).toBeGreaterThan(0);
+      expect(tx.currency).toBe('usd');
+      expect(['income', 'expense', 'transfer']).toContain(tx.type);
+      expect(tx.provider).toBe('stripe');
+    }
+  });
+
+  it('transactions from xero have provider set to xero', () => {
+    const transactions = mockTransactions(5, 'xero');
+    for (const tx of transactions) {
+      expect(tx.provider).toBe('xero');
+    }
+  });
+});

package/tests/tools/revenue_summary.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { Transaction } from '../../src/types.js';
+
+// ─── Mock Stripe SDK ──────────────────────────────────────────────────────────
+vi.mock('stripe', () => {
+  const transactions = [
+    { id: 'txn_1', created: 1743465600, amount: 10000, currency: 'usd', description: 'Revenue A', type: 'charge', metadata: {} },
+    { id: 'txn_2', created: 1743552000, amount: 20000, currency: 'usd', description: 'Revenue B', type: 'charge', metadata: {} },
+    { id: 'txn_3', created: 1743638400, amount: 15000, currency: 'usd', description: 'Revenue C', type: 'charge', metadata: {} },
+    { id: 'txn_4', created: 1743724800, amount: 5000,  currency: 'usd', description: 'Revenue D', type: 'charge', metadata: {} },
+    { id: 'txn_5', created: 1743811200, amount: -500,  currency: 'usd', description: 'Stripe fee', type: 'stripe_fee', metadata: {} },
+    { id: 'txn_6', created: 1743897600, amount: -1000, currency: 'usd', description: 'Refund', type: 'payment_refund', metadata: {} },
+  ];
+
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({ data: transactions, 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('revenue_summary — provider layer', () => {
+  beforeEach(() => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('income transactions have type income', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const incomeTransactions = result.data.filter((t) => t.type === 'income');
+    expect(incomeTransactions.length).toBeGreaterThan(0);
+  });
+
+  it('total revenue = sum of income transaction amounts in cents', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const incomeTransactions = result.data.filter((t) => t.type === 'income');
+    const totalCents = incomeTransactions.reduce((s, t) => s + t.amount, 0);
+    // mock: 10000 + 20000 + 15000 + 5000 = 50000 cents = $500
+    expect(totalCents).toBe(50000);
+    expect(totalCents / 100).toBe(500);
+  });
+
+  it('revenue calculation excludes expense type transactions', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const expenseTransactions = result.data.filter((t) => t.type === 'expense');
+    const incomeTransactions = result.data.filter((t) => t.type === 'income');
+
+    expect(expenseTransactions.length).toBeGreaterThan(0);
+    expect(incomeTransactions.length).toBeGreaterThan(0);
+
+    const incomeIds = new Set(incomeTransactions.map((t) => t.id));
+    for (const exp of expenseTransactions) {
+      expect(incomeIds.has(exp.id)).toBe(false);
+    }
+  });
+
+  it('average transaction = total / count', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const incomeTransactions = result.data.filter((t) => t.type === 'income');
+    const totalCents = incomeTransactions.reduce((s, t) => s + t.amount, 0);
+    const expectedAvg = totalCents / incomeTransactions.length / 100;
+
+    expect(expectedAvg).toBeCloseTo(125.00, 2);  // 50000 / 4 / 100 = 125
+  });
+});
+
+describe('revenue_summary — period grouping logic', () => {
+  it('groups transactions by month correctly', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-01-10T00:00:00Z', amount: 10000, currency: 'usd', description: 'Jan sale', type: 'income', provider: 'stripe' },
+      { id: 't2', date: '2026-01-25T00:00:00Z', amount: 20000, currency: 'usd', description: 'Jan sale 2', type: 'income', provider: 'stripe' },
+      { id: 't3', date: '2026-02-15T00:00:00Z', amount: 15000, currency: 'usd', description: 'Feb sale', type: 'income', provider: 'stripe' },
+    ];
+
+    const byMonth: Record<string, number> = {};
+    for (const t of transactions) {
+      const month = t.date.substring(0, 7);
+      byMonth[month] = (byMonth[month] ?? 0) + t.amount;
+    }
+
+    expect(byMonth['2026-01']).toBe(30000);
+    expect(byMonth['2026-02']).toBe(15000);
+  });
+
+  it('monthly growth rate is positive when revenue increasing', () => {
+    const monthlyRevenues = [10000, 12000, 14400];
+    const growthRates = [];
+
+    for (let i = 1; i < monthlyRevenues.length; i++) {
+      const rate = (monthlyRevenues[i] - monthlyRevenues[i - 1]) / monthlyRevenues[i - 1];
+      growthRates.push(rate);
+    }
+
+    for (const rate of growthRates) {
+      expect(rate).toBeGreaterThan(0);
+    }
+    expect(growthRates[0]).toBeCloseTo(0.2, 2);
+  });
+
+  it('monthly growth rate is negative when revenue declining', () => {
+    const monthlyRevenues = [14000, 12000, 10000];
+    const growthRate = (monthlyRevenues[1] - monthlyRevenues[0]) / monthlyRevenues[0];
+    expect(growthRate).toBeLessThan(0);
+  });
+
+  it('growth rate is zero when revenue flat', () => {
+    const monthlyRevenues = [10000, 10000, 10000];
+    const growthRate = (monthlyRevenues[1] - monthlyRevenues[0]) / monthlyRevenues[0];
+    expect(growthRate).toBe(0);
+  });
+
+  it('top customers are sorted by revenue descending', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-01-10T00:00:00Z', amount: 5000, currency: 'usd', description: 'Customer B', type: 'income', provider: 'stripe' },
+      { id: 't2', date: '2026-01-15T00:00:00Z', amount: 50000, currency: 'usd', description: 'Customer A', type: 'income', provider: 'stripe' },
+      { id: 't3', date: '2026-01-20T00:00:00Z', amount: 10000, currency: 'usd', description: 'Customer C', type: 'income', provider: 'stripe' },
+    ];
+
+    const byCustomer: Record<string, number> = {};
+    for (const t of transactions) {
+      byCustomer[t.description] = (byCustomer[t.description] ?? 0) + t.amount;
+    }
+
+    const topCustomers = Object.entries(byCustomer)
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, 3)
+      .map(([name, amount]) => ({ name, amount: amount / 100 }));
+
+    expect(topCustomers[0].name).toBe('Customer A');
+    expect(topCustomers[0].amount).toBe(500);
+    expect(topCustomers[1].name).toBe('Customer C');
+    expect(topCustomers[2].name).toBe('Customer B');
+  });
+
+  it('returns 0 revenue for empty transaction list', () => {
+    const transactions: Transaction[] = [];
+    const incomeTransactions = transactions.filter((t) => t.type === 'income');
+    const totalRevenue = incomeTransactions.reduce((s, t) => s + t.amount, 0) / 100;
+
+    expect(totalRevenue).toBe(0);
+  });
+
+  it('average transaction is 0 when no income', () => {
+    const incomeTransactions: Transaction[] = [];
+    const avg = incomeTransactions.length > 0
+      ? incomeTransactions.reduce((s, t) => s + t.amount, 0) / incomeTransactions.length / 100
+      : 0;
+
+    expect(avg).toBe(0);
+  });
+
+  it('transaction count matches income transactions only', async () => {
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    const adapter = new StripeAdapter();
+    const result = await adapter.getTransactions({});
+
+    const incomeCount = result.data.filter((t) => t.type === 'income').length;
+    expect(incomeCount).toBe(4);  // From mock: 4 charge transactions
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    testTimeout: 30000,
+    globals: true,
+    environment: 'node',
+  },
+});