@dizzlkheinz/ynab-mcpb 0.13.1 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dizzlkheinz/ynab-mcpb",
-  "version": "0.13.1",
+  "version": "0.15.1",
   "description": "Model Context Protocol server for YNAB (You Need A Budget) integration",
   "main": "dist/index.js",
   "type": "module",
@@ -67,10 +67,14 @@
   "license": "AGPL-3.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.22.0",
+    "chrono-node": "^2.9.0",
     "csv-parse": "^6.1.0",
     "d3-array": "^3.2.4",
     "date-fns": "^4.1.0",
+    "dayjs": "^1.11.19",
     "dotenv": "^17.2.1",
+    "fuzzball": "^2.2.3",
+    "papaparse": "^5.5.3",
     "ynab": "^2.9.0",
     "zod": "^4.1.11",
     "zod-validation-error": "^5.0.0"
@@ -79,6 +83,7 @@
     "@eslint/js": "^9.35.0",
     "@types/d3-array": "^3.2.1",
     "@types/node": "^24.5.2",
+    "@types/papaparse": "^5.5.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "esbuild": "^0.25.10",

package/scripts/test-recommendations.ts

@@ -4,7 +4,7 @@
  */
 
 import { analyzeReconciliation } from '../src/tools/reconciliation/analyzer.js';
-import { DEFAULT_MATCHING_CONFIG } from '../src/tools/reconciliation/types.js';
+import { DEFAULT_CONFIG as DEFAULT_MATCHING_CONFIG } from '../src/tools/reconciliation/matcher.js';
 
 // Test data from user's scenario
 const csvContent = `Date,Description,Amount

package/src/__tests__/tools/reconciliation/csvParser.integration.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { parseCSV } from '../../../tools/reconciliation/csvParser.js';
+import { findMatches } from '../../../tools/reconciliation/matcher.js';
+import { normalizeYNABTransaction } from '../../../tools/reconciliation/ynabAdapter.js';
+
+describe('CSV Parser Integration Tests', () => {
+  describe('TD Bank CSV', () => {
+    const tdCSV = `Date,Description,Amount
+09/15/2025,SHELL STATION 1234 TORONTO ON,-45.23
+09/16/2025,AMZN MKTP CA*1A2B3C4,-127.99
+09/17/2025,PAYROLL DEPOSIT ABC CORP,2500.00`;
+
+    it('should parse TD CSV correctly', () => {
+      const result = parseCSV(tdCSV, { preset: 'td' });
+
+      expect(result.errors).toHaveLength(0);
+      expect(result.transactions).toHaveLength(3);
+      expect(result.transactions[0].amount).toBe(-45230); // Milliunits!
+      expect(result.transactions[0].payee).toBe('SHELL STATION 1234 TORONTO ON');
+      expect(result.transactions[0].date).toBe('2025-09-15');
+    });
+  });
+
+  describe('RBC Debit/Credit CSV', () => {
+    const rbcCSV = `Transaction Date,Description 1,Debit,Credit
+2025-09-15,SHELL GAS,45.23,
+2025-09-16,TRANSFER FROM SAVINGS,,500.00`;
+
+    it('should parse RBC CSV with debit/credit columns', () => {
+      const result = parseCSV(rbcCSV, { preset: 'rbc' });
+
+      expect(result.errors).toHaveLength(0);
+      expect(result.transactions).toHaveLength(2);
+      expect(result.transactions[0].amount).toBe(-45230); // Debit = negative milliunits
+      expect(result.transactions[1].amount).toBe(500000); // Credit = positive milliunits
+    });
+  });
+
+  describe('Ambiguous Debit/Credit Warning', () => {
+    const ambiguousCSV = `Transaction Date,Description,Debit,Credit
+2025-09-15,WEIRD TXN,50.00,25.00`;
+
+    it('should warn when both debit and credit have values', () => {
+      const result = parseCSV(ambiguousCSV, { preset: 'rbc' });
+
+      expect(result.warnings).toHaveLength(1);
+      expect(result.warnings[0].message).toContain('Both Debit');
+      expect(result.transactions[0].amount).toBe(-50000); // Uses debit
+    });
+  });
+
+  describe('European Number Format', () => {
+    const euroCSV = `Date,Amount,Description
+15/09/2025,"1.234,56",Big Purchase`;
+
+    it('should handle European number format', () => {
+      const result = parseCSV(euroCSV);
+
+      expect(result.transactions[0].amount).toBe(1234560); // 1234.56 in milliunits
+    });
+  });
+});
+
+describe('Matcher Integration Tests', () => {
+  const mockYNABTransactions = [
+    {
+      id: 'y1',
+      date: '2025-09-15',
+      amount: -45230,
+      payee_name: 'Shell',
+      category_name: 'Gas',
+      cleared: 'uncleared',
+      approved: true,
+    },
+    {
+      id: 'y2',
+      date: '2025-09-17',
+      amount: -127990,
+      payee_name: 'Amazon',
+      category_name: 'Shopping',
+      cleared: 'uncleared',
+      approved: true,
+    },
+  ].map((t) => normalizeYNABTransaction(t as any));
+
+  it('should achieve high confidence matches with exact integer comparison', () => {
+    const bankCSV = `Date,Description,Amount
+09/15/2025,SHELL STATION 1234,-45.23
+09/16/2025,AMZN MKTP CA*ABC123,-127.99`;
+
+    const parsed = parseCSV(bankCSV);
+    const matches = findMatches(parsed.transactions, mockYNABTransactions);
+
+    // Shell: exact amount match (both -45230 milliunits)
+    expect(matches[0].confidence).toBe('high');
+    expect(matches[0].bestMatch?.scores.amount).toBe(100);
+
+    // Amazon: exact amount match (both -127990 milliunits)
+    expect(matches[1].confidence).toBe('high');
+    expect(matches[1].bestMatch?.scores.amount).toBe(100);
+  });
+
+  it('should use exact integer comparison (no float precision issues)', () => {
+    // Both are now integers - no floating point comparison needed!
+    const bankTxn = {
+      id: 'b1',
+      date: '2025-09-15',
+      amount: -45230, // Integer milliunits
+      payee: 'Shell',
+      sourceRow: 2,
+      raw: { date: '09/15/2025', amount: '-45.23', description: 'Shell' },
+    };
+
+    const ynabTxn = {
+      id: 'y1',
+      date: '2025-09-15',
+      amount: -45230, // Integer milliunits - direct from YNAB API
+      payee: 'Shell',
+      memo: null,
+      categoryName: 'Gas',
+      cleared: 'uncleared' as const,
+      approved: true,
+    };
+
+    const matches = findMatches([bankTxn], [ynabTxn]);
+    // Exact match because integers compare exactly: -45230 === -45230
+    expect(matches[0].bestMatch?.scores.amount).toBe(100);
+  });
+});

package/src/__tests__/tools/reconciliation/real-world.integration.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { parseCSV } from '../../../tools/reconciliation/csvParser.js';
+
+describe('Real World CSV Validation (Simulated)', () => {
+  describe('Wealthsimple', () => {
+    // Simulated content based on real structure
+    const wsContent = `Date,Payee,Amount
+2025-11-21,"Amazon.Ca*B03Vv2Ss0",-42.68
+2025-11-21,"Amazon.Ca*B06I19Si0",-33.56
+2025-11-21,"Amzn Mktp Ca*B07U50Um2",-37.79`;
+
+    it('should parse Wealthsimple export correctly', () => {
+      const result = parseCSV(wsContent);
+
+      expect(result.errors).toHaveLength(0);
+      expect(result.transactions.length).toBe(3);
+
+      const first = result.transactions[0];
+      expect(first.date).toBe('2025-11-21');
+      expect(first.payee).toContain('Amazon');
+      expect(first.amount).toBe(-42680); // -42.68
+    });
+  });
+
+  describe('TD Canada Trust', () => {
+    // Simulated content based on real structure (Headerless)
+    // Date, Desc, Debit, Credit, Balance
+    const tdContent = `11/21/2025,EvoCarShare,23.87,,132.91
+11/19/2025,KOODO MOBILE PAC,43.68,,109.04
+11/14/2025,PAYMENT - THANK YOU,,1378.31,0.00`;
+
+    it('should parse TD export correctly using preset', () => {
+      // TD export is headerless
+      // We expect the 'td' preset to handle header: false and index mappings
+      const result = parseCSV(tdContent, { preset: 'td' });
+
+      expect(result.errors).toHaveLength(0);
+      expect(result.transactions.length).toBe(3);
+
+      const first = result.transactions[0];
+      // 11/21/2025
+      expect(first.date).toBe('2025-11-21');
+      expect(first.payee).toBe('EvoCarShare');
+      // 23.87 Debit = Outflow = Negative
+      expect(first.amount).toBe(-23870);
+
+      const third = result.transactions[2];
+      // 1378.31 Credit = Inflow = Positive
+      expect(third.payee).toBe('PAYMENT - THANK YOU');
+      expect(third.amount).toBe(1378310);
+    });
+  });
+});

package/src/server/errorHandler.ts

@@ -12,6 +12,7 @@ interface ErrorResponseFormatter {
  */
 
 export const enum YNABErrorCode {
+  BAD_REQUEST = 400,
   UNAUTHORIZED = 401,
   FORBIDDEN = 403,
   NOT_FOUND = 404,
@@ -54,6 +55,11 @@ export class YNABAPIError extends Error {
     this.code = code;
     this.originalError = originalError;
   }
+
+  // Expose status as an alias for code for backward compatibility with tests
+  get status(): YNABErrorCode {
+    return this.code;
+  }
 }
 
 export class ValidationError extends Error {
@@ -106,7 +112,12 @@ export class ErrorHandler {
       formattedText = this.formatter.format(errorResponse);
     } catch {
       // Fallback to JSON.stringify if formatter fails
-      formattedText = JSON.stringify(errorResponse, null, 2);
+      try {
+        formattedText = JSON.stringify(errorResponse, null, 2);
+      } catch {
+        // Final fallback if JSON serialization fails (e.g. circular references)
+        formattedText = `Error processing request: ${this.getGenericErrorMessage(context)}`;
+      }
     }
 
     return {
@@ -135,7 +146,9 @@ export class ErrorHandler {
   private createErrorResponse(error: unknown, context: string): ErrorResponse {
     // Handle custom error types
     if (error instanceof YNABAPIError) {
-      const sanitizedDetails = this.sanitizeErrorDetails(error.originalError);
+      const ynabDetails = this.extractYNABApiError(error.originalError);
+      const detailsToSanitize = ynabDetails?.details || error.originalError;
+      const sanitizedDetails = this.sanitizeErrorDetails(detailsToSanitize);
       return {
         error: {
           code: error.code,
@@ -216,7 +229,22 @@ export class ErrorHandler {
 
     // Fallback for unknown errors
     // Preserve the original error message for debugging while sanitizing sensitive data
-    const errorMessage = error instanceof Error ? error.message : String(error);
+    let errorMessage: string;
+    if (error instanceof Error) {
+      errorMessage = error.message;
+    } else if (typeof error === 'string') {
+      errorMessage = error;
+    } else if (error && typeof error === 'object') {
+      // Handle plain objects (e.g., YNAB SDK errors that aren't Error instances)
+      try {
+        errorMessage = JSON.stringify(error, null, 2);
+      } catch {
+        // Circular reference or other JSON issue
+        errorMessage = Object.prototype.toString.call(error);
+      }
+    } else {
+      errorMessage = String(error);
+    }
     const sanitizedDetails = this.sanitizeErrorDetails(errorMessage);
 
     return {
@@ -264,6 +292,8 @@ export class ErrorHandler {
    */
   private getUserFriendlyMessage(code: YNABErrorCode | SecurityErrorCode, context: string): string {
     switch (code) {
+      case YNABErrorCode.BAD_REQUEST:
+        return 'The request was invalid. Please check your input data.';
       case YNABErrorCode.UNAUTHORIZED:
         return 'Your YNAB access token is invalid or has expired. Please check your token and try again.';
       case YNABErrorCode.FORBIDDEN:
@@ -288,6 +318,12 @@ export class ErrorHandler {
    */
   private getErrorSuggestions(code: YNABErrorCode | SecurityErrorCode, context: string): string[] {
     switch (code) {
+      case YNABErrorCode.BAD_REQUEST:
+        return [
+          'Check that all required fields are correct',
+          'Verify that dates are in the correct format (ISO 8601)',
+          'Ensure amounts are valid numbers',
+        ];
       case YNABErrorCode.UNAUTHORIZED:
         return [
           'Go to https://app.youneedabudget.com/settings/developer to generate a new access token',
@@ -401,6 +437,8 @@ export class ErrorHandler {
    */
   private getErrorMessage(code: YNABErrorCode, context: string): string {
     switch (code) {
+      case YNABErrorCode.BAD_REQUEST:
+        return 'Bad request - invalid parameters';
       case YNABErrorCode.UNAUTHORIZED:
         return 'Invalid or expired YNAB access token';
       case YNABErrorCode.FORBIDDEN:
@@ -535,6 +573,7 @@ export class ErrorHandler {
    */
   private mapHttpStatusToErrorCode(status: number): YNABErrorCode | null {
     switch (status) {
+      case YNABErrorCode.BAD_REQUEST:
       case YNABErrorCode.UNAUTHORIZED:
       case YNABErrorCode.FORBIDDEN:
       case YNABErrorCode.NOT_FOUND:
@@ -571,11 +610,19 @@ export class ErrorHandler {
    * Extracts structured YNAB API error information
    */
   private extractYNABApiError(error: unknown): { code: YNABErrorCode; details?: string } | null {
-    if (!error || typeof error !== 'object' || !('error' in (error as Record<string, unknown>))) {
+    if (!error || typeof error !== 'object') {
       return null;
     }
 
-    const payload = (error as { error?: unknown }).error;
+    let payload = (error as { error?: unknown }).error;
+
+    if (!payload) {
+      const responseData = (error as { response?: { data?: unknown } }).response?.data;
+      if (responseData && typeof responseData === 'object') {
+        payload = (responseData as { error?: unknown }).error;
+      }
+    }
+
     if (!payload || typeof payload !== 'object') {
       return null;
     }

package/src/tools/reconcileAdapter.ts

@@ -76,7 +76,7 @@ interface LegacyBalanceReconciliation {
 
 const toBankTransactionView = (txn: BankTransaction, currency: string) => ({
   ...txn,
-  amount_money: toMoneyValueFromDecimal(txn.amount, currency),
+  amount_money: toMoneyValue(txn.amount, currency),
 });
 
 const toYNABTransactionView = (txn: YNABTransaction, currency: string) => ({
@@ -85,15 +85,20 @@ const toYNABTransactionView = (txn: YNABTransaction, currency: string) => ({
 });
 
 const convertMatch = (match: TransactionMatch, currency: string) => ({
-  ...match,
-  bank_transaction: toBankTransactionView(match.bank_transaction, currency),
-  ynab_transaction: match.ynab_transaction
-    ? toYNABTransactionView(match.ynab_transaction, currency)
+  bank_transaction: toBankTransactionView(match.bankTransaction, currency),
+  ynab_transaction: match.ynabTransaction
+    ? toYNABTransactionView(match.ynabTransaction, currency)
     : undefined,
   candidates: match.candidates?.map((candidate) => ({
     ...candidate,
     ynab_transaction: toYNABTransactionView(candidate.ynab_transaction, currency),
   })),
+  confidence: match.confidence,
+  confidence_score: match.confidenceScore,
+  match_reason: match.matchReason,
+  top_confidence: match.topConfidence,
+  action_hint: match.actionHint,
+  recommendation: match.recommendation,
 });
 
 const convertInsight = (insight: ReconciliationInsight) => ({

package/src/tools/reconciliation/__tests__/adapter.test.ts

@@ -34,38 +34,41 @@ const buildAnalysis = (): ReconciliationAnalysis => ({
   },
   auto_matches: [
     {
-      bank_transaction: {
+      bankTransaction: {
         id: 'bank-1',
         date: '2025-10-15',
-        amount: -45.23,
+        amount: -45230,
         payee: 'Shell Gas',
-        original_csv_row: 2,
+        sourceRow: 2,
+        raw: { date: '2025-10-15', amount: '-45.23', description: 'Shell Gas' },
       },
-      ynab_transaction: {
+      ynabTransaction: {
         id: 'ynab-1',
         date: '2025-10-14',
         amount: -45230,
-        payee_name: 'Shell',
-        category_name: 'Auto',
+        payee: 'Shell',
+        categoryName: 'Auto',
         cleared: 'uncleared',
         approved: true,
+        memo: null,
       },
       candidates: [],
       confidence: 'high',
-      confidence_score: 97,
-      match_reason: 'exact_amount_and_date',
-      top_confidence: 97,
-      action_hint: 'mark_cleared',
+      confidenceScore: 97,
+      matchReason: 'exact_amount_and_date',
+      topConfidence: 97,
+      actionHint: 'mark_cleared',
     },
   ],
   suggested_matches: [
     {
-      bank_transaction: {
+      bankTransaction: {
         id: 'bank-2',
         date: '2025-10-20',
-        amount: -60,
+        amount: -60000,
         payee: 'Amazon',
-        original_csv_row: 5,
+        sourceRow: 5,
+        raw: { date: '2025-10-20', amount: '-60.00', description: 'Amazon' },
       },
       candidates: [
         {
@@ -73,10 +76,11 @@ const buildAnalysis = (): ReconciliationAnalysis => ({
             id: 'ynab-2',
             date: '2025-10-19',
             amount: -60000,
-            payee_name: 'Amazon Online',
-            category_name: 'Shopping',
+            payee: 'Amazon Online',
+            categoryName: 'Shopping',
             cleared: 'uncleared',
             approved: true,
+            memo: null,
           },
           confidence: 75,
           match_reason: 'amount_and_date_fuzzy_payee',
@@ -84,18 +88,19 @@ const buildAnalysis = (): ReconciliationAnalysis => ({
         },
       ],
       confidence: 'medium',
-      confidence_score: 75,
-      match_reason: 'amount_and_date_fuzzy_payee',
-      top_confidence: 75,
+      confidenceScore: 75,
+      matchReason: 'amount_and_date_fuzzy_payee',
+      topConfidence: 75,
     },
   ],
   unmatched_bank: [
     {
       id: 'bank-3',
       date: '2025-10-25',
-      amount: 22.22,
+      amount: 22220,
       payee: 'EvoCarShare',
-      original_csv_row: 7,
+      sourceRow: 7,
+      raw: { date: '2025-10-25', amount: '22.22', description: 'EvoCarShare' },
     },
   ],
   unmatched_ynab: [
@@ -103,10 +108,11 @@ const buildAnalysis = (): ReconciliationAnalysis => ({
       id: 'ynab-3',
       date: '2025-10-26',
       amount: -15000,
-      payee_name: 'Coffee Shop',
-      category_name: 'Dining',
+      payee: 'Coffee Shop',
+      categoryName: 'Dining',
       cleared: 'cleared',
       approved: true,
+      memo: null,
     },
   ],
   balance_info: {