@dizzlkheinz/ynab-mcpb 0.15.0 → 0.16.0

package/src/tools/reconciliation/csvParser.ts

@@ -95,11 +95,35 @@ export const BANK_PRESETS: Record<string, BankPreset> = {
   },
 };
 
+/**
+ * Safe delimiters allowed for CSV parsing.
+ * Restricted to common, safe characters to prevent injection attacks.
+ */
+export const SAFE_DELIMITERS = [',', ';', '\t', '|', ' '] as const;
+export type SafeDelimiter = (typeof SAFE_DELIMITERS)[number];
+
+/**
+ * Validates that a delimiter is safe for CSV parsing.
+ * @throws {Error} if delimiter is not in the safe list
+ */
+function validateDelimiter(delimiter: string): asserts delimiter is SafeDelimiter {
+  if (!SAFE_DELIMITERS.includes(delimiter as SafeDelimiter)) {
+    throw new Error(
+      `Unsafe delimiter "${delimiter}". Allowed delimiters: ${SAFE_DELIMITERS.join(', ')}`,
+    );
+  }
+}
+
 export interface ParseCSVOptions {
   /** Bank preset key (e.g., 'td', 'rbc') */
   preset?: string;
   /** Multiply all amounts by -1 */
   invertAmounts?: boolean;
+  /**
+   * Explicit CSV delimiter override (defaults to PapaParse auto-detection).
+   * Must be one of: comma (,), semicolon (;), tab (\t), pipe (|), or space ( )
+   */
+  delimiter?: string;
   /** Manual column overrides */
   columns?: {
     date?: string;
@@ -201,6 +225,11 @@ export function parseCSV(content: string, options: ParseCSVOptions = {}): CSVPar
   const errors: ParseError[] = [];
   const warnings: ParseWarning[] = [];
 
+  // Security: Validate delimiter if provided
+  if (options.delimiter) {
+    validateDelimiter(options.delimiter);
+  }
+
   // Security: Check file size limit
   const MAX_BYTES = options.maxBytes ?? 10 * 1024 * 1024; // 10MB default
   if (content.length > MAX_BYTES) {
@@ -244,6 +273,7 @@ export function parseCSV(content: string, options: ParseCSVOptions = {}): CSVPar
     dynamicTyping: false, // We'll handle type conversion ourselves
     skipEmptyLines: true,
     transformHeader: (h) => h.trim(),
+    ...(options.delimiter ? { delimiter: options.delimiter } : {}),
   });
 
   if (parsed.errors.length > 0) {
@@ -381,14 +411,46 @@ export function parseCSV(content: string, options: ParseCSVOptions = {}): CSVPar
 
     if (amountCol) {
       rawAmount = getValue(amountCol)?.trim() ?? '';
-      amountMilliunits = dollarStringToMilliunits(rawAmount);
+      const parsedAmount = parseAmount(rawAmount);
+      if (!parsedAmount.valid) {
+        errors.push({
+          row: rowNum,
+          field: 'amount',
+          message: parsedAmount.reason ?? `Invalid amount: "${rawAmount}"`,
+          rawValue: rawAmount,
+        });
+        continue;
+      }
+      amountMilliunits = parsedAmount.valueMilliunits;
     } else if (debitCol && creditCol) {
       const debit = getValue(debitCol)?.trim() ?? '';
       const credit = getValue(creditCol)?.trim() ?? '';
       rawAmount = debit || credit;
 
-      const debitMilliunits = dollarStringToMilliunits(debit);
-      const creditMilliunits = dollarStringToMilliunits(credit);
+      const parsedDebit = parseAmount(debit);
+      const parsedCredit = parseAmount(credit);
+
+      if (!parsedDebit.valid && debit) {
+        errors.push({
+          row: rowNum,
+          field: 'amount',
+          message: parsedDebit.reason ?? `Invalid debit amount: "${debit}"`,
+          rawValue: debit,
+        });
+        continue;
+      }
+      if (!parsedCredit.valid && credit) {
+        errors.push({
+          row: rowNum,
+          field: 'amount',
+          message: parsedCredit.reason ?? `Invalid credit amount: "${credit}"`,
+          rawValue: credit,
+        });
+        continue;
+      }
+
+      const debitMilliunits = parsedDebit.valid ? parsedDebit.valueMilliunits : 0;
+      const creditMilliunits = parsedCredit.valid ? parsedCredit.valueMilliunits : 0;
 
       // Warn if both debit and credit have values (ambiguous)
       if (Math.abs(debitMilliunits) > 0 && Math.abs(creditMilliunits) > 0) {
@@ -402,7 +464,13 @@ export function parseCSV(content: string, options: ParseCSVOptions = {}): CSVPar
       } else if (Math.abs(creditMilliunits) > 0) {
         amountMilliunits = Math.abs(creditMilliunits); // Credits are inflows (positive)
       } else {
-        amountMilliunits = 0;
+        errors.push({
+          row: rowNum,
+          field: 'amount',
+          message: 'Missing debit/credit amount',
+          rawValue: `${debit}|${credit}`,
+        });
+        continue;
       }
 
       // Warn if debit column contains negative value (unusual)
@@ -415,16 +483,6 @@ export function parseCSV(content: string, options: ParseCSVOptions = {}): CSVPar
       continue;
     }
 
-    if (!Number.isFinite(amountMilliunits)) {
-      errors.push({
-        row: rowNum,
-        field: 'amount',
-        message: `Invalid amount: "${rawAmount}"`,
-        rawValue: rawAmount,
-      });
-      continue;
-    }
-
     // Apply amount inversion if needed
     const multiplier = options.invertAmounts ? -1 : (preset?.amountMultiplier ?? 1);
     amountMilliunits *= multiplier;
@@ -589,8 +647,14 @@ function detectPreset(columns: string[]): BankPreset | undefined {
 const CURRENCY_SYMBOLS = /[$€£¥]/g;
 const CURRENCY_CODES = /\b(CAD|USD|EUR|GBP)\b/gi;
 
-function dollarStringToMilliunits(str: string): number {
-  if (!str) return 0;
+function parseAmount(str: string): {
+  valid: boolean;
+  valueMilliunits: number;
+  reason?: string;
+} {
+  if (!str || !str.trim()) {
+    return { valid: false, valueMilliunits: 0, reason: 'Missing amount value' };
+  }
 
   let cleaned = str.replace(CURRENCY_SYMBOLS, '').replace(CURRENCY_CODES, '').trim();
 
@@ -610,8 +674,10 @@ function dollarStringToMilliunits(str: string): number {
   }
 
   const dollars = parseFloat(cleaned);
-  if (!Number.isFinite(dollars)) return 0;
+  if (!Number.isFinite(dollars)) {
+    return { valid: false, valueMilliunits: 0, reason: `Invalid amount: "${str}"` };
+  }
 
   // Convert to milliunits: $1.00 → 1000
-  return Math.round(dollars * 1000);
+  return { valid: true, valueMilliunits: Math.round(dollars * 1000) };
 }

package/src/tools/reconciliation/executor.ts

@@ -113,6 +113,11 @@ function truncateMemo(memo: string | null | undefined): string {
   return memo.substring(0, MAX_MEMO_LENGTH - 3) + '...';
 }
 
+interface StatementWindow {
+  start?: Date;
+  end?: Date;
+}
+
 interface PreparedBulkCreateEntry {
   bankTransaction: BankTransaction;
   saveTransaction: SaveTransaction;
@@ -144,6 +149,53 @@ function generateBulkImportId(
   return `YNAB:bulk:${digest}`;
 }
 
+function parseISODate(dateStr: string | undefined): Date | undefined {
+  if (!dateStr) return undefined;
+  const d = new Date(dateStr);
+  return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+function resolveStatementWindow(
+  params: ReconcileAccountRequest,
+  analysisDateRange?: string | undefined,
+): StatementWindow | undefined {
+  const start = parseISODate(params.statement_start_date);
+  const end =
+    parseISODate(params.statement_end_date ?? params.statement_date) ??
+    // If only start provided, end stays undefined
+    undefined;
+
+  if (start || end) {
+    const window: StatementWindow = {};
+    if (start) window.start = start;
+    if (end) window.end = end;
+    return window;
+  }
+
+  if (analysisDateRange && analysisDateRange.includes(' to ')) {
+    const [rawStart, rawEnd] = analysisDateRange.split(' to ').map((part) => part.trim());
+    const parsedStart = parseISODate(rawStart);
+    const parsedEnd = parseISODate(rawEnd);
+    if (parsedStart || parsedEnd) {
+      const window: StatementWindow = {};
+      if (parsedStart) window.start = parsedStart;
+      if (parsedEnd) window.end = parsedEnd;
+      return window;
+    }
+  }
+
+  return undefined;
+}
+
+function isWithinStatementWindow(dateStr: string, window: StatementWindow): boolean {
+  const date = parseISODate(dateStr);
+  if (!date) return false;
+
+  if (window.start && date < window.start) return false;
+  if (window.end && date > window.end) return false;
+  return true;
+}
+
 export async function executeReconciliation(options: ExecutionOptions): Promise<ExecutionResult> {
   const { analysis, params, ynabAPI, budgetId, accountId, initialAccount, currencyCode } = options;
   const actions_taken: ExecutionActionRecord[] = [];
@@ -202,7 +254,12 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
     ? sortByDateDescending(analysis.unmatched_bank)
     : [];
   const orderedAutoMatches = sortMatchesByBankDateDescending(analysis.auto_matches);
-  const orderedUnmatchedYNAB = sortByDateDescending(analysis.unmatched_ynab);
+  const statementWindow = resolveStatementWindow(params, analysis.summary.statement_date_range);
+  const orderedUnmatchedYNAB = sortByDateDescending(
+    statementWindow
+      ? analysis.unmatched_ynab.filter((txn) => isWithinStatementWindow(txn.date, statementWindow))
+      : analysis.unmatched_ynab,
+  );
 
   let bulkOperationDetails: BulkOperationDetails | undefined;
 

package/src/tools/reconciliation/index.ts

@@ -22,6 +22,7 @@ import type { DeltaFetcher } from '../deltaFetcher.js';
 import { resolveDeltaFetcherArgs } from '../deltaSupport.js';
 import { detectSignInversion } from './signDetector.js';
 import { normalizeYNABTransactions } from './ynabAdapter.js';
+import type { BankTransaction } from './types.js';
 
 // Re-export types for external use
 export type * from './types.js';
@@ -168,9 +169,9 @@ export async function handleReconcileAccount(
           date: 0.15,
           payee: 0.35,
         },
-        dateToleranceDays: params.date_tolerance_days ?? 5,
+        dateToleranceDays: params.date_tolerance_days ?? 7,
         amountToleranceMilliunits: (params.amount_tolerance_cents ?? 1) * 10,
-        autoMatchThreshold: params.auto_match_threshold ?? 90,
+        autoMatchThreshold: params.auto_match_threshold ?? 85,
         suggestedMatchThreshold: params.suggestion_threshold ?? 60,
         minimumCandidateScore: 40,
         exactAmountBonus: 10,
@@ -216,6 +217,8 @@ export async function handleReconcileAccount(
       const budgetResponse = await ynabAPI.budgets.getBudgetById(params.budget_id);
       const currencyCode = budgetResponse.data.budget?.currency_format?.iso_code ?? 'USD';
 
+      const narrativeNotes: string[] = [];
+
       // Prepare CSV parsing options from request
       const dateFormat = mapCsvDateFormatToHint(params.csv_format?.date_format);
       const csvOptions: ParseCSVOptions = {
@@ -240,6 +243,9 @@ export async function handleReconcileAccount(
         ...(params.csv_format?.has_header !== undefined && {
           header: params.csv_format.has_header,
         }),
+        ...(params.csv_format?.delimiter !== undefined && {
+          delimiter: params.csv_format.delimiter,
+        }),
       };
 
       // Load CSV content from either inline data or filesystem path
@@ -256,42 +262,44 @@ export async function handleReconcileAccount(
         }
       }
 
-      // Fetch YNAB transactions for the account
-      // Auto-detect date range from CSV if not explicitly provided
+      if (!csvContent.trim()) {
+        throw new Error('CSV content is empty after reading the provided source.');
+      }
+
+      // Initial parse without inversion for date window + sign detection
+      let rawCsvResult: CSVParseResult;
+      try {
+        rawCsvResult = parseCSV(csvContent, {
+          ...csvOptions,
+          invertAmounts: false,
+        });
+      } catch (error) {
+        const message =
+          error instanceof Error && error.message
+            ? error.message
+            : 'Unknown error while parsing CSV';
+        throw new Error(`Failed to parse CSV data: ${message}`);
+      }
+
+      // Fetch YNAB transactions for the account using inferred date window
       let sinceDate: Date;
-      let parseResult: CSVParseResult | undefined;
+      let dateWindowSource:
+        | 'statement_start_date'
+        | 'csv_min_date_with_buffer'
+        | 'fallback_90_days';
 
       if (params.statement_start_date) {
-        // User provided explicit start date
         sinceDate = new Date(params.statement_start_date);
+        dateWindowSource = 'statement_start_date';
+      } else if (rawCsvResult.transactions.length > 0) {
+        sinceDate = inferSinceDateFromTransactions(rawCsvResult.transactions);
+        dateWindowSource = 'csv_min_date_with_buffer';
       } else {
-        // Auto-detect from CSV content using new parser
-        try {
-          parseResult = parseCSV(csvContent, {
-            ...csvOptions,
-            invertAmounts: shouldInvertBankAmounts,
-          });
-
-          if (parseResult.transactions.length > 0) {
-            // Find min date
-            const dates = parseResult.transactions
-              .map((t) => new Date(t.date).getTime())
-              .filter((t) => !isNaN(t));
-            if (dates.length > 0) {
-              const minTime = Math.min(...dates);
-              const minDateObj = new Date(minTime);
-              minDateObj.setDate(minDateObj.getDate() - 7); // 7-day buffer
-              sinceDate = minDateObj;
-            } else {
-              sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-            }
-          } else {
-            sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-          }
-        } catch {
-          // Fallback to 90 days if CSV parsing fails
-          sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-        }
+        sinceDate = fallbackSinceDate();
+        dateWindowSource = 'fallback_90_days';
+        narrativeNotes.push(
+          'CSV contained no parsable transactions for date detection; fetched the last 90 days from YNAB.',
+        );
       }
 
       const sinceDateString = sinceDate.toISOString().split('T')[0];
@@ -308,33 +316,33 @@ export async function handleReconcileAccount(
           );
 
       const ynabTransactions = transactionsResult.data;
+      const normalizedYNAB = normalizeYNABTransactions(ynabTransactions);
 
       // Smart sign detection: If invert_bank_amounts not explicitly set, auto-detect
       let finalInvertAmounts = shouldInvertBankAmounts;
-      if (params.invert_bank_amounts === undefined && csvContent) {
-        // Parse CSV without inversion to get raw amounts
-        const rawParseResult = parseCSV(csvContent, {
-          ...csvOptions,
-          invertAmounts: false, // Don't invert yet
-        });
-
-        if (rawParseResult.transactions.length > 0 && ynabTransactions.length > 0) {
-          // Normalize YNAB transactions for comparison
-          const normalizedYNAB = normalizeYNABTransactions(ynabTransactions);
-
-          // Detect if signs are mismatched
-          const needsInversion = detectSignInversion(rawParseResult.transactions, normalizedYNAB);
-
-          finalInvertAmounts = needsInversion;
-
-          // If detection result differs from default, invalidate parseResult
-          // to force re-parsing with correct inversion
-          if (needsInversion !== shouldInvertBankAmounts && parseResult) {
-            parseResult = undefined;
-          }
+      if (
+        params.invert_bank_amounts === undefined &&
+        rawCsvResult.transactions.length > 0 &&
+        normalizedYNAB.length > 0
+      ) {
+        const needsInversion = detectSignInversion(rawCsvResult.transactions, normalizedYNAB);
+
+        if (needsInversion !== finalInvertAmounts) {
+          narrativeNotes.push(
+            needsInversion
+              ? 'Detected bank CSV amounts opposite YNAB; inverting bank amounts for matching.'
+              : 'Detected bank CSV amounts already align with YNAB; using CSV amounts as-is.',
+          );
         }
+
+        finalInvertAmounts = needsInversion;
       }
 
+      const parseResult =
+        finalInvertAmounts === false
+          ? rawCsvResult
+          : parseCSV(csvContent, { ...csvOptions, invertAmounts: finalInvertAmounts });
+
       const auditMetadata = {
         data_freshness: getDataFreshness(transactionsResult, forceFullRefresh),
         data_source: getAuditDataSource(transactionsResult, forceFullRefresh),
@@ -347,11 +355,32 @@ export async function handleReconcileAccount(
           transactions_cached: transactionsResult.wasCached,
           delta_merge_applied: transactionsResult.usedDelta,
         },
+        csv: {
+          rows: parseResult.meta.totalRows,
+          transactions: parseResult.transactions.length,
+          errors: parseResult.errors.length,
+          warnings: parseResult.warnings.length,
+          delimiter: parseResult.meta.detectedDelimiter,
+        },
+        date_window: {
+          since_date: sinceDateString,
+          source: dateWindowSource,
+        },
+        sign_detection: {
+          default_invert: shouldInvertBankAmounts,
+          final_invert: finalInvertAmounts,
+        },
+      };
+
+      const initialAccount: AccountSnapshot = {
+        balance: accountData.balance,
+        cleared_balance: accountData.cleared_balance,
+        uncleared_balance: accountData.uncleared_balance,
       };
 
       // Perform analysis
       const analysis = analyzeReconciliation(
-        parseResult ?? csvContent,
+        parseResult,
         params.csv_file_path,
         ynabTransactions,
         adjustedStatementBalance,
@@ -361,14 +390,9 @@ export async function handleReconcileAccount(
         params.budget_id,
         finalInvertAmounts, // Use smart-detected value
         csvOptions,
+        initialAccount,
       );
 
-      const initialAccount: AccountSnapshot = {
-        balance: accountData.balance,
-        cleared_balance: accountData.cleared_balance,
-        uncleared_balance: accountData.uncleared_balance,
-      };
-
       let executionData: LegacyReconciliationResult | undefined;
       const wantsBalanceVerification = Boolean(params.statement_date);
       const shouldExecute =
@@ -402,6 +426,9 @@ export async function handleReconcileAccount(
       if (csvFormatForPayload !== undefined) {
         adapterOptions.csvFormat = csvFormatForPayload;
       }
+      if (narrativeNotes.length > 0) {
+        adapterOptions.notes = narrativeNotes;
+      }
 
       const payload = buildReconciliationPayload(analysis, adapterOptions, executionData);
 
@@ -491,3 +518,27 @@ function mapCsvFormatForPayload(format: ReconcileAccountRequest['csv_format'] |
     payee_column: coerceString(format.description_column, '') ?? null,
   };
 }
+
+function fallbackSinceDate(): Date {
+  const date = new Date();
+  date.setDate(date.getDate() - 90);
+  return date;
+}
+
+function inferSinceDateFromTransactions(transactions: BankTransaction[]): Date {
+  if (transactions.length === 0) {
+    return fallbackSinceDate();
+  }
+
+  const timestamps = transactions
+    .map((t) => new Date(t.date).getTime())
+    .filter((time) => !Number.isNaN(time));
+
+  if (timestamps.length === 0) {
+    return fallbackSinceDate();
+  }
+
+  const minDate = new Date(Math.min(...timestamps));
+  minDate.setDate(minDate.getDate() - 7); // Add a small buffer
+  return minDate;
+}