financeops-mcp 0.1.0

package/src/lib/audit.ts

@@ -0,0 +1,92 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const DB_PATH = path.join(os.homedir(), '.financeops', 'audit.db');
+
+let db: Database.Database | null = null;
+
+function getDb(dbPath?: string): Database.Database {
+  if (db) return db;
+
+  const targetPath = dbPath ?? DB_PATH;
+  const dir = path.dirname(targetPath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  db = new Database(targetPath);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS audit_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool TEXT NOT NULL,
+      provider TEXT,
+      timestamp TEXT DEFAULT (datetime('now')),
+      input_summary TEXT,
+      success INTEGER DEFAULT 1,
+      error TEXT
+    )
+  `);
+
+  return db;
+}
+
+export interface AuditEntry {
+  tool: string;
+  provider?: string;
+  input_summary?: string;
+  success?: boolean;
+  error?: string;
+}
+
+export function logAudit(entry: AuditEntry, dbPath?: string): void {
+  const database = getDb(dbPath);
+
+  const stmt = database.prepare(`
+    INSERT INTO audit_log (tool, provider, input_summary, success, error)
+    VALUES (@tool, @provider, @input_summary, @success, @error)
+  `);
+
+  stmt.run({
+    tool: entry.tool,
+    provider: entry.provider ?? null,
+    input_summary: entry.input_summary ?? null,
+    success: entry.success !== false ? 1 : 0,
+    error: entry.error ?? null,
+  });
+}
+
+/**
+ * Delete entries older than maxAgeDays.
+ * Called on server start (Important Fix I9: only call from main, not from singleton).
+ */
+export function cleanup(maxAgeDays: number = 90, dbPath?: string): void {
+  const database = getDb(dbPath);
+
+  database.prepare(`
+    DELETE FROM audit_log
+    WHERE timestamp < datetime('now', '-' || ? || ' days')
+  `).run(maxAgeDays);
+}
+
+export function getAuditLog(limit: number = 100, dbPath?: string): AuditEntry[] {
+  const database = getDb(dbPath);
+
+  return database.prepare(`
+    SELECT tool, provider, timestamp, input_summary, success, error
+    FROM audit_log
+    ORDER BY id DESC
+    LIMIT ?
+  `).all(limit) as AuditEntry[];
+}
+
+/** Reset the singleton — for testing only. */
+export function resetAuditDb(): void {
+  if (db) {
+    db.close();
+    db = null;
+  }
+}

package/src/lib/providers.ts

@@ -0,0 +1,29 @@
+/**
+ * Critical Fix 1: Cached provider factory.
+ * Adapters are created once and reused across calls to avoid:
+ * - Repeated credential validation
+ * - Multiple Stripe client instances
+ * - Multiple Xero token file reads
+ */
+import { StripeAdapter } from '../adapters/stripe.js';
+import { XeroAdapter } from '../adapters/xero.js';
+import type { FinanceProvider } from '../adapters/types.js';
+
+const cache = new Map<string, FinanceProvider>();
+
+export function getProvider(name: 'stripe' | 'xero'): FinanceProvider {
+  if (cache.has(name)) return cache.get(name)!;
+
+  const adapter: FinanceProvider = name === 'stripe' ? new StripeAdapter() : new XeroAdapter();
+  cache.set(name, adapter);
+  return adapter;
+}
+
+export function getProviders(names: ('stripe' | 'xero')[]): FinanceProvider[] {
+  return names.map((n) => getProvider(n));
+}
+
+/** Clear the cache — useful for testing. */
+export function clearProviderCache(): void {
+  cache.clear();
+}

package/src/premium/gate.ts

@@ -0,0 +1,24 @@
+/**
+ * Premium gate — reads PRO_LICENSE dynamically from environment.
+ * CRITICAL: Do NOT cache the env variable at module load time.
+ * Must re-read process.env.PRO_LICENSE on every call to support
+ * runtime license changes (e.g., in tests or when env is updated).
+ */
+
+export class ProRequiredError extends Error {
+  constructor(tool: string) {
+    super(`Tool "${tool}" requires a PRO_LICENSE. Set the PRO_LICENSE environment variable.`);
+    this.name = 'ProRequiredError';
+  }
+}
+
+export function isPro(): boolean {
+  // Dynamic read — NOT cached
+  return Boolean(process.env.PRO_LICENSE);
+}
+
+export function requirePro(tool: string): void {
+  if (!isPro()) {
+    throw new ProRequiredError(tool);
+  }
+}

package/src/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Core domain types for FinanceOps MCP.
+ * All monetary amounts are in the smallest currency unit (cents).
+ * Example: 15000 = €150.00
+ */
+
+export interface Transaction {
+  id: string;
+  date: string;           // ISO 8601
+  amount: number;         // Smallest currency unit (cents). 15000 = €150.00
+  currency: string;       // ISO 4217 lowercase, e.g. "usd"
+  description: string;
+  category?: string;
+  type: 'income' | 'expense' | 'transfer';
+  provider: 'stripe' | 'xero';
+  metadata?: Record<string, string>;
+}
+
+export interface Invoice {
+  id: string;
+  number: string;
+  customer_name: string;
+  customer_email?: string;
+  amount: number;           // Smallest currency unit (cents)
+  currency: string;
+  status: 'paid' | 'pending' | 'overdue' | 'draft' | 'voided';
+  due_date: string;         // ISO 8601
+  issued_date: string;      // ISO 8601
+  paid_date?: string;       // ISO 8601
+  provider: 'stripe' | 'xero';
+
+  // Read-only computed fields from Xero (do NOT write these back)
+  readonly amount_due?: number;
+  readonly amount_paid?: number;
+  readonly amount_credited?: number;
+}
+
+export interface Balance {
+  currency: string;
+  available: number;  // Smallest currency unit (cents)
+  pending: number;    // Smallest currency unit (cents)
+  provider: 'stripe' | 'xero';
+}
+
+export interface Expense {
+  id: string;
+  date: string;           // ISO 8601
+  amount: number;         // Smallest currency unit (cents)
+  currency: string;
+  description: string;
+  category: string;
+  provider: 'stripe' | 'xero';
+}
+
+export interface Subscription {
+  id: string;
+  customer_name: string;
+  amount: number;         // Smallest currency unit (cents)
+  currency: string;
+  interval: 'month' | 'year';
+  status: 'active' | 'canceled' | 'past_due' | 'trialing';
+  current_period_start: string;  // ISO 8601
+  current_period_end: string;    // ISO 8601
+  provider: 'stripe' | 'xero';
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  has_more: boolean;
+  next_cursor?: string;
+}
+
+export interface PnLReport {
+  period: string;
+  date_from: string;
+  date_to: string;
+  currency: string;
+  revenue: number;          // In major currency units (e.g. 150.00)
+  cogs: number;
+  gross_profit: number;
+  gross_margin_pct: number;
+  operating_expenses: number;
+  net_income: number;
+  by_category: Record<string, number>;
+}
+
+export interface CashFlowForecast {
+  period_months: number;
+  generated_at: string;
+  historical_monthly_income: number;    // Average over 3-month lookback (major units)
+  historical_monthly_expenses: number;  // Average over 3-month lookback (major units)
+  trend_pct: number;                    // Monthly growth rate as decimal
+  scenarios: {
+    conservative: MonthlyForecast[];
+    realistic: MonthlyForecast[];
+    optimistic: MonthlyForecast[];
+  };
+}
+
+export interface MonthlyForecast {
+  month: string;  // YYYY-MM
+  income: number;
+  expenses: number;
+  net: number;
+  cumulative_net: number;
+}
+
+export interface ReconciliationResult {
+  matched: MatchedPair[];
+  unmatched_stripe: Transaction[];
+  unmatched_xero: Transaction[];
+  summary: {
+    total_stripe: number;
+    total_xero: number;
+    matched_count: number;
+    unmatched_stripe_count: number;
+    unmatched_xero_count: number;
+  };
+}
+
+export interface MatchedPair {
+  stripe: Transaction;
+  xero: Transaction;
+  confidence: number;  // 0-1
+}
+
+export interface Anomaly {
+  id: string;
+  type: 'duplicate' | 'large_variance' | 'missed_recurring' | 'unusual_timing';
+  severity: 'low' | 'medium' | 'high';
+  transaction?: Transaction;
+  description: string;
+  amount?: number;
+  date?: string;
+}
+
+export interface TaxSummary {
+  provider: 'stripe' | 'xero';
+  period: 'quarter' | 'year';
+  jurisdiction?: string;
+  total_taxable_amount: number;   // Major units
+  total_tax_collected: number;    // Major units
+  total_tax_owed: number;         // Major units
+  by_rate: TaxByRate[];
+  filing_period: string;
+}
+
+export interface TaxByRate {
+  rate: number;           // e.g. 0.2 for 20%
+  rate_label: string;     // e.g. "20% VAT"
+  taxable_amount: number;
+  tax_amount: number;
+}

package/tests/adapters/stripe.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock the stripe module before importing the adapter
+vi.mock('stripe', () => {
+  const mockStripe = vi.fn().mockImplementation(() => ({
+    balanceTransactions: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          {
+            id: 'txn_001',
+            created: 1743465600,  // 2026-04-01T00:00:00Z
+            amount: 15000,        // 150.00 USD in cents
+            currency: 'usd',
+            description: 'Payment from customer',
+            type: 'charge',
+            metadata: {},
+          },
+          {
+            id: 'txn_002',
+            created: 1743552000,  // 2026-04-02T00:00:00Z
+            amount: -500,         // -5.00 fee
+            currency: 'usd',
+            description: 'Stripe fee',
+            type: 'stripe_fee',
+            metadata: {},
+          },
+        ],
+        has_more: false,
+      }),
+    },
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [
+          { currency: 'usd', amount: 500000 },
+          { currency: 'eur', amount: 150000 },
+        ],
+        pending: [
+          { currency: 'usd', amount: 25000 },
+        ],
+      }),
+    },
+    invoices: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          {
+            id: 'in_001',
+            number: 'INV-001',
+            customer_name: 'Test Customer',
+            customer_email: 'test@example.com',
+            amount_due: 9900,
+            currency: 'usd',
+            status: 'paid',
+            due_date: 1748736000,
+            created: 1746057600,
+            status_transitions: { paid_at: 1748044800 },
+          },
+        ],
+        has_more: false,
+      }),
+    },
+    subscriptions: {
+      list: vi.fn().mockResolvedValue({
+        data: [
+          {
+            id: 'sub_001',
+            customer: 'cus_xxx',
+            currency: 'usd',
+            status: 'active',
+            current_period_start: 1743465600,
+            current_period_end: 1746057600,
+            items: {
+              data: [
+                {
+                  price: {
+                    unit_amount: 4900,
+                    recurring: { interval: 'month' },
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      }),
+    },
+  }));
+
+  return { default: mockStripe };
+});
+
+describe('StripeAdapter', () => {
+  let adapter: import('../../src/adapters/stripe.js').StripeAdapter;
+
+  beforeEach(async () => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    adapter = new StripeAdapter();
+  });
+
+  it('throws if STRIPE_SECRET_KEY is missing', async () => {
+    delete process.env.STRIPE_SECRET_KEY;
+    const { StripeAdapter } = await import('../../src/adapters/stripe.js');
+    expect(() => new StripeAdapter()).toThrow('STRIPE_SECRET_KEY');
+    process.env.STRIPE_SECRET_KEY = 'sk_test_xxx';
+  });
+
+  it('getTransactions returns amounts in cents', async () => {
+    const result = await adapter.getTransactions({});
+    expect(result.data).toHaveLength(2);
+
+    const first = result.data[0];
+    expect(first.amount).toBe(15000);  // 150.00 USD as cents
+    expect(first.currency).toBe('usd');
+    expect(first.provider).toBe('stripe');
+  });
+
+  it('getTransactions maps charge type to income', async () => {
+    const result = await adapter.getTransactions({});
+    expect(result.data[0].type).toBe('income');
+  });
+
+  it('getTransactions maps stripe_fee type to expense', async () => {
+    const result = await adapter.getTransactions({});
+    expect(result.data[1].type).toBe('expense');
+  });
+
+  it('getTransactions includes pagination cursor when has_more is true', async () => {
+    // The mock returns has_more: false
+    const result = await adapter.getTransactions({});
+    expect(result.has_more).toBe(false);
+    expect(result.next_cursor).toBeUndefined();
+  });
+
+  it('getBalances returns amounts in cents', async () => {
+    const balances = await adapter.getBalances();
+    expect(balances.length).toBeGreaterThan(0);
+
+    const usdBalance = balances.find((b) => b.currency === 'usd');
+    expect(usdBalance).toBeDefined();
+    expect(usdBalance!.available).toBe(500000);   // $5000.00 in cents
+    expect(usdBalance!.pending).toBe(25000);       // $250.00 in cents
+    expect(usdBalance!.provider).toBe('stripe');
+  });
+
+  it('getInvoices returns invoice data with amounts in cents', async () => {
+    const result = await adapter.getInvoices({});
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0].amount).toBe(9900);  // $99.00 in cents
+    expect(result.data[0].status).toBe('paid');
+  });
+});

package/tests/adapters/xero.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const TOKEN_PATH = path.join(os.homedir(), '.financeops', 'xero-tokens.json');
+
+function writeTokens(tokens: object) {
+  const dir = path.dirname(TOKEN_PATH);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(TOKEN_PATH, JSON.stringify(tokens));
+}
+
+function removeTokens() {
+  if (fs.existsSync(TOKEN_PATH)) fs.unlinkSync(TOKEN_PATH);
+}
+
+describe('XeroAdapter', () => {
+  beforeEach(() => {
+    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';
+    delete process.env.XERO_ACCESS_TOKEN;
+  });
+
+  afterEach(() => {
+    removeTokens();
+    vi.restoreAllMocks();
+  });
+
+  it('throws if XERO_TENANT_ID is missing', async () => {
+    delete process.env.XERO_TENANT_ID;
+    const { XeroAdapter } = await import('../../src/adapters/xero.js');
+    expect(() => new XeroAdapter()).toThrow('XERO_TENANT_ID');
+    process.env.XERO_TENANT_ID = 'tenant_test';
+  });
+
+  it('validates date format — rejects invalid dates', async () => {
+    // Write valid tokens so adapter doesn't fail on token load
+    writeTokens({
+      access_token: 'tok',
+      refresh_token: 'ref',
+      expires_at: Date.now() + 60 * 60 * 1000,
+    });
+
+    const { XeroAdapter } = await import('../../src/adapters/xero.js');
+    const adapter = new XeroAdapter();
+
+    await expect(adapter.getTransactions({ date_from: '01-01-2026' })).rejects.toThrow(
+      'Invalid date format'
+    );
+    await expect(adapter.getTransactions({ date_from: "2026-01-01' OR '1'='1" })).rejects.toThrow(
+      'Invalid date format'
+    );
+  });
+
+  it('accepts valid YYYY-MM-DD dates', async () => {
+    writeTokens({
+      access_token: 'tok',
+      refresh_token: 'ref',
+      expires_at: Date.now() + 60 * 60 * 1000,
+    });
+
+    // Mock fetch
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({
+        BankTransactions: [
+          {
+            BankTransactionID: 'bt_001',
+            Date: '2026-03-15',
+            Total: 150.0,
+            CurrencyCode: 'USD',
+            Type: 'RECEIVE',
+            Reference: 'Payment received',
+          },
+        ],
+      }),
+    }));
+
+    const { XeroAdapter } = await import('../../src/adapters/xero.js');
+    const adapter = new XeroAdapter();
+    const result = await adapter.getTransactions({ date_from: '2026-01-01', date_to: '2026-03-31' });
+
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0].amount).toBe(15000);  // 150.00 * 100 = cents
+  });
+
+  it('converts Xero Total to cents correctly', async () => {
+    writeTokens({
+      access_token: 'tok',
+      refresh_token: 'ref',
+      expires_at: Date.now() + 60 * 60 * 1000,
+    });
+
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({
+        BankTransactions: [
+          {
+            BankTransactionID: 'bt_002',
+            Date: '2026-03-01',
+            Total: 99.99,
+            CurrencyCode: 'USD',
+            Type: 'RECEIVE',
+            Reference: 'Test',
+          },
+        ],
+      }),
+    }));
+
+    const { XeroAdapter } = await import('../../src/adapters/xero.js');
+    const adapter = new XeroAdapter();
+    const result = await adapter.getTransactions({});
+
+    // Math.round(99.99 * 100) = 9999
+    expect(result.data[0].amount).toBe(9999);
+  });
+
+  it('refreshes token when expired', async () => {
+    // Write expired tokens
+    writeTokens({
+      access_token: 'old_token',
+      refresh_token: 'valid_refresh',
+      expires_at: Date.now() - 1000,  // Already expired
+    });
+
+    const fetchMock = vi.fn()
+      // First call: token refresh endpoint
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: 'new_access_token',
+          refresh_token: 'new_refresh_token',
+          expires_in: 1800,
+        }),
+      })
+      // Second call: actual API request
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({ BankTransactions: [] }),
+      });
+
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { XeroAdapter } = await import('../../src/adapters/xero.js');
+    const adapter = new XeroAdapter();
+    await adapter.getTransactions({});
+
+    // Verify token refresh was called first
+    const firstCall = fetchMock.mock.calls[0][0] as string;
+    expect(firstCall).toContain('identity.xero.com');
+  });
+
+  it('getInvoices returns paginated results with page-based cursor', async () => {
+    writeTokens({
+      access_token: 'tok',
+      refresh_token: 'ref',
+      expires_at: Date.now() + 60 * 60 * 1000,
+    });
+
+    // Return exactly 100 invoices to trigger has_more: true
+    const mockInvoices = Array.from({ length: 100 }, (_, i) => ({
+      InvoiceID: `inv_${i}`,
+      InvoiceNumber: `INV-${i}`,
+      Contact: { Name: `Customer ${i}`, EmailAddress: `c${i}@test.com` },
+      Total: 100,
+      CurrencyCode: 'USD',
+      Status: 'AUTHORISED',
+      DueDate: '2026-05-01',
+      Date: '2026-03-01',
+    }));
+
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({ Invoices: mockInvoices }),
+    }));
+
+    const { XeroAdapter } = await import('../../src/adapters/xero.js');
+    const adapter = new XeroAdapter();
+    const result = await adapter.getInvoices({});
+
+    expect(result.has_more).toBe(true);
+    expect(result.next_cursor).toBe('2');  // Next page number
+    expect(result.data).toHaveLength(100);
+  });
+});