financeops-mcp 0.1.0

package/src/analysis/reconciliation.ts

@@ -0,0 +1,117 @@
+import type { Transaction, ReconciliationResult, MatchedPair } from '../types.js';
+
+const DATE_TOLERANCE_DAYS = 2;
+
+/**
+ * Levenshtein distance between two strings.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, (_, i) =>
+    Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+  );
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
+  }
+
+  return dp[m][n];
+}
+
+/**
+ * Normalized Levenshtein distance: 0 = identical, 1 = completely different.
+ */
+function normalizedLevenshtein(a: string, b: string): number {
+  if (a.length === 0 && b.length === 0) return 0;
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 0;
+  return levenshtein(a, b) / maxLen;
+}
+
+/**
+ * Reconcile Stripe transactions against Xero transactions.
+ *
+ * Matching criteria:
+ * 1. Exact amount match (in cents)
+ * 2. Date within ±2 days
+ * 3. HARD GATE: description similarity >= 20% (Critical Fix 4)
+ *    Prevents false positives like "AWS hosting $50" matching "Employee lunch $50"
+ *
+ * Confidence: weighted score (40% date proximity + 60% description similarity).
+ */
+export function reconcile(
+  stripeTransactions: Transaction[],
+  xeroTransactions: Transaction[]
+): ReconciliationResult {
+  const matchedStripeIds = new Set<string>();
+  const matchedXeroIds = new Set<string>();
+  const matched: MatchedPair[] = [];
+
+  for (const st of stripeTransactions) {
+    const stDate = new Date(st.date).getTime();
+
+    let bestMatch: { xero: Transaction; confidence: number } | null = null;
+
+    for (const xt of xeroTransactions) {
+      if (matchedXeroIds.has(xt.id)) continue;
+
+      // 1. Exact amount match required
+      if (st.amount !== xt.amount) continue;
+
+      // 2. Date tolerance check
+      const xtDate = new Date(xt.date).getTime();
+      const daysDiff = Math.abs(stDate - xtDate) / (1000 * 60 * 60 * 24);
+      if (daysDiff > DATE_TOLERANCE_DAYS) continue;
+
+      // 3. HARD GATE: description similarity (Critical Fix 4)
+      const descSimilarity =
+        1 -
+        normalizedLevenshtein(
+          st.description.toLowerCase(),
+          xt.description.toLowerCase()
+        );
+      if (descSimilarity < 0.2) continue;
+
+      // Confidence score
+      const dateScore = 1 - daysDiff / DATE_TOLERANCE_DAYS;
+      const confidence = dateScore * 0.4 + descSimilarity * 0.6;
+
+      if (!bestMatch || confidence > bestMatch.confidence) {
+        bestMatch = { xero: xt, confidence };
+      }
+    }
+
+    if (bestMatch) {
+      matchedStripeIds.add(st.id);
+      matchedXeroIds.add(bestMatch.xero.id);
+      matched.push({
+        stripe: st,
+        xero: bestMatch.xero,
+        confidence: Math.round(bestMatch.confidence * 1000) / 1000,
+      });
+    }
+  }
+
+  const unmatchedStripe = stripeTransactions.filter((t) => !matchedStripeIds.has(t.id));
+  const unmatchedXero = xeroTransactions.filter((t) => !matchedXeroIds.has(t.id));
+
+  return {
+    matched,
+    unmatched_stripe: unmatchedStripe,
+    unmatched_xero: unmatchedXero,
+    summary: {
+      total_stripe: stripeTransactions.length,
+      total_xero: xeroTransactions.length,
+      matched_count: matched.length,
+      unmatched_stripe_count: unmatchedStripe.length,
+      unmatched_xero_count: unmatchedXero.length,
+    },
+  };
+}

package/src/analysis/tax.ts

@@ -0,0 +1,98 @@
+import type { Transaction, TaxSummary, TaxByRate } from '../types.js';
+
+/**
+ * Default VAT/tax rates by jurisdiction.
+ * Key = jurisdiction code, value = array of applicable rates.
+ */
+const TAX_RATES_BY_JURISDICTION: Record<string, number[]> = {
+  EU: [0.0, 0.05, 0.12, 0.2, 0.21, 0.25],
+  NL: [0.0, 0.09, 0.21],
+  DE: [0.0, 0.07, 0.19],
+  FR: [0.0, 0.055, 0.1, 0.2],
+  GB: [0.0, 0.05, 0.2],
+  US: [0.0, 0.05, 0.07, 0.08, 0.1],
+  DEFAULT: [0.0, 0.1, 0.2],
+};
+
+const STANDARD_RATE_BY_JURISDICTION: Record<string, number> = {
+  NL: 0.21,
+  DE: 0.19,
+  FR: 0.2,
+  GB: 0.2,
+  US: 0.08,
+  EU: 0.21,
+  DEFAULT: 0.2,
+};
+
+/**
+ * Calculate VAT/sales tax summary from transactions.
+ * Input amounts are in cents; output is in major currency units.
+ *
+ * This is a simplified v1 calculation. For production:
+ * - Use actual tax metadata from the payment processor
+ * - Apply jurisdiction-specific rules
+ */
+export function calculateTax(
+  transactions: Transaction[],
+  period: 'quarter' | 'year',
+  jurisdiction?: string
+): TaxSummary {
+  const provider = transactions.length > 0 ? transactions[0].provider : 'stripe';
+  const jur = (jurisdiction ?? 'DEFAULT').toUpperCase();
+
+  // Standard rate for the jurisdiction
+  const standardRate = STANDARD_RATE_BY_JURISDICTION[jur] ?? STANDARD_RATE_BY_JURISDICTION['DEFAULT'];
+
+  // Income transactions are taxable
+  const taxableTransactions = transactions.filter((t) => t.type === 'income');
+
+  // Group by assumed tax rate (in v1, we assume all income at standard rate unless metadata says otherwise)
+  const byRate: Record<number, { taxable: number; tax: number }> = {};
+
+  for (const t of taxableTransactions) {
+    // Try to get tax rate from metadata
+    const rateStr = t.metadata?.tax_rate;
+    const rate = rateStr ? parseFloat(rateStr) : standardRate;
+
+    // Tax-exclusive: taxable amount = amount / (1 + rate), tax = amount - taxable
+    const taxableAmountCents = t.amount / (1 + rate);
+    const taxAmountCents = t.amount - taxableAmountCents;
+
+    if (!byRate[rate]) byRate[rate] = { taxable: 0, tax: 0 };
+    byRate[rate].taxable += taxableAmountCents;
+    byRate[rate].tax += taxAmountCents;
+  }
+
+  const byRateResult: TaxByRate[] = Object.entries(byRate).map(([rateStr, totals]) => {
+    const rate = parseFloat(rateStr);
+    return {
+      rate,
+      rate_label: rate === 0 ? 'Exempt' : `${(rate * 100).toFixed(0)}% VAT`,
+      taxable_amount: Math.round(totals.taxable) / 100,
+      tax_amount: Math.round(totals.tax) / 100,
+    };
+  });
+
+  const totalTaxableCents = Object.values(byRate).reduce((sum, r) => sum + r.taxable, 0);
+  const totalTaxCents = Object.values(byRate).reduce((sum, r) => sum + r.tax, 0);
+
+  // Filing period label
+  const now = new Date();
+  const year = now.getFullYear();
+  const quarter = Math.ceil((now.getMonth() + 1) / 3);
+  const filingPeriod =
+    period === 'year'
+      ? `${year}`
+      : `Q${quarter} ${year}`;
+
+  return {
+    provider,
+    period,
+    jurisdiction: jur !== 'DEFAULT' ? jur : undefined,
+    total_taxable_amount: Math.round(totalTaxableCents) / 100,
+    total_tax_collected: Math.round(totalTaxCents) / 100,
+    total_tax_owed: Math.round(totalTaxCents) / 100,  // In v1, owed = collected
+    by_rate: byRateResult,
+    filing_period: filingPeriod,
+  };
+}