@dizzlkheinz/ynab-mcpb 0.12.2 → 0.15.0

package/src/tools/reconciliation/reportFormatter.ts

@@ -173,16 +173,17 @@ function formatBankTransactionLine(txn: BankTransaction): string {
  * Format a suggested match line
  */
 function formatSuggestedMatchLine(match: TransactionMatch): string {
-  const bankTxn = match.bank_transaction;
+  const bankTxn = match.bankTransaction;
   const amountStr = formatAmount(bankTxn.amount);
-  const confidenceStr = `${match.confidence_score}%`;
+  const confidenceStr = `${match.confidenceScore}%`;
   return `   ${bankTxn.date} - ${bankTxn.payee.substring(0, 35).padEnd(35)} ${amountStr} (${confidenceStr} confidence)`;
 }
 
 /**
- * Format an amount for display
+ * Format an amount for display (input in milliunits)
  */
-function formatAmount(amount: number): string {
+function formatAmount(amountMilli: number): string {
+  const amount = amountMilli / 1000;
   const sign = amount >= 0 ? '+' : '-';
   const absAmount = Math.abs(amount);
   return `${sign}$${absAmount.toFixed(2)}`.padStart(10);
@@ -336,6 +337,8 @@ export function formatBalanceInfo(balance: BalanceInfo): string {
 /**
  * Format transaction list (helper for detailed reports)
  */
+type FormattableYnabTransaction = YNABTransaction & { payee_name?: string | null };
+
 export function formatTransactionList(
   transactions: BankTransaction[] | YNABTransaction[],
   maxItems: number = 10,
@@ -344,14 +347,16 @@ export function formatTransactionList(
   const toShow = transactions.slice(0, maxItems);
 
   for (const txn of toShow) {
-    if ('payee' in txn) {
-      // Bank transaction
-      lines.push(formatBankTransactionLine(txn));
+    if ('cleared' in txn) {
+      // YNAB transaction (normalized)
+      const ynabTxn = txn as FormattableYnabTransaction;
+      const payee = ynabTxn.payee_name ?? ynabTxn.payee ?? 'Unknown';
+      lines.push(
+        `   ${ynabTxn.date} - ${payee.substring(0, 40).padEnd(40)} ${formatAmount(ynabTxn.amount)}`,
+      );
     } else {
-      // YNAB transaction
-      const amount = txn.amount / 1000; // Convert milliunits to dollars
-      const payee = txn.payee_name ?? 'Unknown';
-      lines.push(`   ${txn.date} - ${payee.substring(0, 40).padEnd(40)} ${formatAmount(amount)}`);
+      // Bank transaction
+      lines.push(formatBankTransactionLine(txn as BankTransaction));
     }
   }
 

package/src/tools/reconciliation/signDetector.ts

@@ -0,0 +1,117 @@
+/**
+ * Smart sign detection for bank transaction imports
+ *
+ * Analyzes a sample of bank and YNAB transactions to determine if
+ * bank amounts need to be inverted to match YNAB's sign convention.
+ */
+
+import type { BankTransaction, NormalizedYNABTransaction } from '../../types/reconciliation.js';
+
+interface SignMatch {
+  bankAmount: number;
+  ynabAmount: number;
+  oppositeSign: boolean;
+}
+
+/**
+ * Detects whether bank transaction amounts need to be inverted
+ * to match YNAB's sign convention.
+ *
+ * Algorithm:
+ * 1. Find matching transactions based on date/amount proximity
+ * 2. For each match, check if signs are opposite
+ * 3. If >50% of matches have opposite signs, return true (needs inversion)
+ *
+ * @param bankTransactions - Raw bank transactions from CSV
+ * @param ynabTransactions - Normalized YNAB transactions
+ * @returns true if bank amounts should be inverted, false otherwise
+ */
+export function detectSignInversion(
+  bankTransactions: BankTransaction[],
+  ynabTransactions: NormalizedYNABTransaction[],
+): boolean {
+  // Edge cases: empty lists
+  if (bankTransactions.length === 0 || ynabTransactions.length === 0) {
+    return false; // Conservative default: don't invert
+  }
+
+  // Sample up to 20 transactions for performance
+  const sampleSize = Math.min(20, bankTransactions.length);
+  const sample = bankTransactions.slice(0, sampleSize);
+
+  const matches: SignMatch[] = [];
+
+  // Try to find matches for each bank transaction
+  for (const bankTxn of sample) {
+    const match = findClosestMatch(bankTxn, ynabTransactions);
+    if (match) {
+      matches.push(match);
+    }
+  }
+
+  // Need at least 1 match to make a determination
+  if (matches.length === 0) {
+    return false; // Conservative default: don't invert
+  }
+
+  // Count how many matches have opposite signs
+  const oppositeSignCount = matches.filter((m) => m.oppositeSign).length;
+  const oppositeSignRatio = oppositeSignCount / matches.length;
+
+  // If more than 50% have opposite signs, inversion is needed
+  return oppositeSignRatio > 0.5;
+}
+
+/**
+ * Find the closest matching YNAB transaction for a bank transaction
+ */
+function findClosestMatch(
+  bankTxn: BankTransaction,
+  ynabTransactions: NormalizedYNABTransaction[],
+): SignMatch | null {
+  const bankDate = new Date(bankTxn.date);
+  const bankAbsAmount = Math.abs(bankTxn.amount);
+
+  let bestMatch: SignMatch | null = null;
+  let bestScore = 0;
+
+  for (const ynabTxn of ynabTransactions) {
+    const ynabDate = new Date(ynabTxn.date);
+    const ynabAbsAmount = Math.abs(ynabTxn.amount);
+
+    // Check if amounts match (within tolerance)
+    const amountDiff = Math.abs(bankAbsAmount - ynabAbsAmount);
+    const amountTolerance = 100; // 10 cents in milliunits
+    if (amountDiff > amountTolerance) {
+      continue; // Amounts too different
+    }
+
+    // Check date proximity
+    const daysDiff = Math.abs(bankDate.getTime() - ynabDate.getTime()) / (1000 * 60 * 60 * 24);
+    if (daysDiff > 7) {
+      continue; // Dates too far apart
+    }
+
+    // Calculate match score (closer = higher score)
+    const amountScore = amountDiff === 0 ? 100 : Math.max(0, 100 - amountDiff / 10);
+    const dateScore = daysDiff === 0 ? 100 : Math.max(0, 100 - daysDiff * 10);
+    const score = amountScore * 0.7 + dateScore * 0.3;
+
+    if (score > bestScore) {
+      bestScore = score;
+
+      // Check if signs are opposite
+      const bankSign = Math.sign(bankTxn.amount);
+      const ynabSign = Math.sign(ynabTxn.amount);
+      const oppositeSign = bankSign !== 0 && ynabSign !== 0 && bankSign !== ynabSign;
+
+      bestMatch = {
+        bankAmount: bankTxn.amount,
+        ynabAmount: ynabTxn.amount,
+        oppositeSign,
+      };
+    }
+  }
+
+  return bestMatch;
+}

package/src/tools/reconciliation/types.ts

@@ -1,48 +1,28 @@
 /**
  * Type definitions for the reconciliation tool
  * Based on the 2025-10-31 reconciliation redesign specification
+ *
+ * IMPORTANT UNIT CONVENTION:
+ * BankTransaction.amount is in MILLIUNITS (integers) in V2 architecture (formerly dollars).
+ * YNABTransaction.amount is in MILLIUNITS (integers).
+ * All internal calculations use milliunits to avoid floating-point errors.
  */
 
 import type { MoneyValue } from '../../utils/money.js';
+import type {
+  BankTransaction as CanonicalBankTransaction,
+  NormalizedYNABTransaction as CanonicalYNABTransaction,
+} from '../../types/reconciliation.js';
+
+// Re-export canonical types as the standard types
+export type BankTransaction = CanonicalBankTransaction;
+export type YNABTransaction = CanonicalYNABTransaction;
 
 /**
  * Matching confidence levels
  */
 export type MatchConfidence = 'high' | 'medium' | 'low' | 'none';
 
-/**
- * Bank transaction parsed from CSV
- */
-export interface BankTransaction {
-  /** Generated UUID for tracking */
-  id: string;
-  /** Transaction date in YYYY-MM-DD format */
-  date: string;
-  /** Amount in dollars */
-  amount: number;
-  /** Payee/merchant name */
-  payee: string;
-  /** Optional memo/description */
-  memo?: string;
-  /** Original CSV row number for debugging */
-  original_csv_row: number;
-}
-
-/**
- * YNAB transaction (simplified from API)
- */
-export interface YNABTransaction {
-  id: string;
-  date: string;
-  /** Amount in milliunits */
-  amount: number;
-  payee_name: string | null;
-  category_name: string | null;
-  cleared: 'cleared' | 'uncleared' | 'reconciled';
-  approved: boolean;
-  memo?: string | null;
-}
-
 /**
  * Match candidate with confidence score
  */
@@ -57,21 +37,21 @@ export interface MatchCandidate {
  * Transaction match result
  */
 export interface TransactionMatch {
-  bank_transaction: BankTransaction;
+  bankTransaction: BankTransaction;
   /** Best matched YNAB transaction (if any) */
-  ynab_transaction?: YNABTransaction;
+  ynabTransaction?: YNABTransaction;
   /** Alternative candidates for suggested matches */
   candidates?: MatchCandidate[];
   /** Confidence level */
   confidence: MatchConfidence;
   /** Confidence score 0-100 */
-  confidence_score: number;
+  confidenceScore: number;
   /** Reason for the match */
-  match_reason: string;
+  matchReason: string;
   /** Top confidence from candidates */
-  top_confidence?: number;
+  topConfidence?: number;
   /** Action hint for user */
-  action_hint?: string;
+  actionHint?: string;
   /** Recommendation text */
   recommendation?: string;
 }
@@ -163,31 +143,29 @@ export interface ReconciliationAction {
 }
 
 /**
- * Matching algorithm configuration
+ * Matching algorithm configuration (V2)
  */
 export interface MatchingConfig {
-  /** Date tolerance in days */
-  dateToleranceDays: number;
-  /** Amount tolerance in cents */
-  amountToleranceCents: number;
-  /** Description similarity threshold (0-1) */
-  descriptionSimilarityThreshold: number;
-  /** Confidence threshold for auto-matching (0-100) */
-  autoMatchThreshold: number;
-  /** Confidence threshold for suggestions (0-100) */
-  suggestionThreshold: number;
-}
+  weights: {
+    amount: number; // Recommended: 0.50
+    date: number; // Recommended: 0.15
+    payee: number; // Recommended: 0.35
+  };
 
-/**
- * Default matching configuration (not type-only for use in code)
- */
-export const DEFAULT_MATCHING_CONFIG = {
-  dateToleranceDays: 2,
-  amountToleranceCents: 1,
-  descriptionSimilarityThreshold: 0.8,
-  autoMatchThreshold: 90,
-  suggestionThreshold: 60,
-};
+  // Tolerances (in MILLIUNITS for amount)
+  amountToleranceMilliunits: number; // Default: 10 (1 cent)
+  dateToleranceDays: number; // Default: 7
+
+  // Thresholds
+  autoMatchThreshold: number; // Default: 85
+  suggestedMatchThreshold: number; // Default: 60
+  minimumCandidateScore: number; // Default: 40
+
+  // Bonuses for perfect matches
+  exactAmountBonus: number; // Default: 10
+  exactDateBonus: number; // Default: 5
+  exactPayeeBonus: number; // Default: 10
+}
 
 /**
  * Parsed CSV data from compareTransactions

package/src/tools/reconciliation/ynabAdapter.ts

@@ -0,0 +1,33 @@
+import type * as ynab from 'ynab';
+import type { NormalizedYNABTransaction } from '../../types/reconciliation.js';
+
+/**
+ * Convert YNAB SDK transaction to normalized format for matching.
+ *
+ * This adapter keeps the YNAB SDK dependency isolated from the
+ * reconciliation core logic.
+ *
+ * NOTE: Amount stays in milliunits - no conversion needed since
+ * YNAB API already uses milliunits natively.
+ */
+export function normalizeYNABTransaction(txn: ynab.TransactionDetail): NormalizedYNABTransaction {
+  return {
+    id: txn.id,
+    date: txn.date,
+    amount: txn.amount, // Already in milliunits - no conversion!
+    payee: txn.payee_name ?? null,
+    memo: txn.memo ?? null,
+    categoryName: txn.category_name ?? null,
+    cleared: txn.cleared,
+    approved: txn.approved,
+  };
+}
+
+/**
+ * Batch convert YNAB transactions.
+ */
+export function normalizeYNABTransactions(
+  txns: ynab.TransactionDetail[],
+): NormalizedYNABTransaction[] {
+  return txns.map(normalizeYNABTransaction);
+}

package/src/tools/schemas/outputs/utilityOutputs.ts

@@ -293,7 +293,7 @@ export const DeltaInfoSchema = z.object({
  *   timestamp: "2025-01-17T12:34:56.789Z",
  *   server: {
  *     name: "ynab-mcp-server",
- *     version: "0.12.0",
+ *     version: "0.13.0",
  *     node_version: "v20.10.0",
  *     // ... other server info
  *   },

package/src/tools/transactionTools.ts

@@ -231,24 +231,9 @@ type BulkTransactionInput = Omit<
   'budget_id' | 'dry_run' | 'subtransactions'
 >;
 
-const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.extend({
-  subtransactions: z.any().optional(),
-})
-  .strict()
-  .superRefine((data, ctx) => {
-    if (data.subtransactions !== undefined) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Subtransactions are not supported in bulk transaction creation',
-        path: ['subtransactions'],
-      });
-    }
-  })
-  .transform((data): BulkTransactionInput => {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { subtransactions, ...rest } = data;
-    return rest;
-  });
+// Schema for bulk transaction creation - subtransactions are not supported
+// The .strict() modifier automatically rejects any fields not in the schema
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
 
 export const CreateTransactionsSchema = z
   .object({
@@ -813,6 +798,10 @@ export async function handleListTransactions(
                 showing: `First ${preview.length} transactions:`,
                 total_count: transactions.length,
                 estimated_size_kb: Math.round(estimatedSize / 1024),
+                cached: cacheHit,
+                cache_info: cacheHit
+                  ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
+                  : 'Fresh data retrieved from YNAB API',
                 preview_transactions: preview.map((transaction) => ({
                   id: transaction.id,
                   date: transaction.date,

package/src/types/reconciliation.ts

@@ -0,0 +1,49 @@
+/**
+ * Canonical bank transaction type used throughout reconciliation.
+ *
+ * AMOUNTS ARE IN MILLIUNITS (integers, 1000 = $1.00).
+ * This matches YNAB's native format and allows exact integer comparison.
+ */
+export interface BankTransaction {
+  /** UUID generated for tracking */
+  id: string;
+  /** ISO date string YYYY-MM-DD */
+  date: string;
+  /** Amount in MILLIUNITS (negative = outflow, positive = inflow) */
+  amount: number;
+  /** Merchant/payee name from CSV */
+  payee: string;
+  /** Optional memo/description */
+  memo?: string;
+  /** Original CSV row number (1-indexed, after header) */
+  sourceRow: number;
+  /** Raw values from CSV for debugging */
+  raw: {
+    date: string;
+    amount: string;
+    description: string;
+  };
+  /** Parser warnings (e.g., ambiguous debit/credit) */
+  warnings?: string[];
+}
+
+/**
+ * YNAB transaction normalized for comparison.
+ *
+ * This interface is intentionally SDK-agnostic. Use the adapter
+ * function in ynabAdapter.ts to convert from ynab.TransactionDetail.
+ *
+ * AMOUNTS ARE IN MILLIUNITS - same as YNAB API native format.
+ * No conversion needed from the SDK.
+ */
+export interface NormalizedYNABTransaction {
+  id: string;
+  date: string; // YYYY-MM-DD
+  /** Amount in MILLIUNITS (same as YNAB API) */
+  amount: number;
+  payee: string | null;
+  memo: string | null;
+  categoryName: string | null;
+  cleared: 'cleared' | 'uncleared' | 'reconciled';
+  approved: boolean;
+}

package/src/utils/baseError.ts

@@ -0,0 +1,7 @@
+export class BaseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,21 @@
+export { BaseError } from './baseError.js';
+export { ValidationError } from './validationError.js';
+import { BaseError } from './baseError.js';
+
+export class ConfigurationError extends BaseError {}
+
+export class AuthenticationError extends BaseError {}
+
+export class YNABRequestError extends BaseError {
+  constructor(
+    public status: number,
+    public statusText: string,
+    public ynabErrorId?: string,
+  ) {
+    super(
+      `YNAB API request failed: ${status} ${statusText}${
+        ynabErrorId ? ` (Error ID: ${ynabErrorId})` : ''
+      }`,
+    );
+  }
+}

package/src/utils/validationError.ts

@@ -0,0 +1,3 @@
+import { BaseError } from './baseError.js';
+
+export class ValidationError extends BaseError {}

package/temp-recon.ts

@@ -0,0 +1,126 @@
+import 'dotenv/config';
+import * as ynab from 'ynab';
+import { executeReconciliation } from './src/tools/reconciliation/executor.js';
+
+async function main() {
+  const token = process.env['YNAB_ACCESS_TOKEN'];
+  if (!token) throw new Error('No token');
+  const api = new ynab.API(token);
+  const budgets = await api.budgets.getBudgets();
+  const budgetId = budgets.data.budgets[0]?.id;
+  if (!budgetId) throw new Error('no budget');
+  const accounts = await api.accounts.getAccounts(budgetId);
+  const account = accounts.data.accounts.find((a) => !a.closed);
+  if (!account) throw new Error('no account');
+  const snapshot = {
+    balance: account.balance,
+    cleared_balance: account.cleared_balance ?? account.balance,
+    uncleared_balance: account.uncleared_balance ?? 0,
+  };
+  const count = 2;
+  const transactionAmount = 7;
+  const clearedDollars = snapshot.cleared_balance / 1000;
+  const totalDelta = transactionAmount * count;
+  const statementBalance = clearedDollars + totalDelta;
+  const today = new Date().toISOString().slice(0, 10);
+  const unmatchedBank = Array.from({ length: count }, (_, i) => {
+    const date = new Date(Date.now() + i * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    return {
+      id: `integration-bank-${i}`,
+      date,
+      amount: transactionAmount,
+      payee: `Integration Payee ${i}`,
+      memo: `Integration memo ${i}`,
+      original_csv_row: i + 1,
+    };
+  });
+  const analysis = {
+    success: true,
+    phase: 'analysis',
+    summary: {
+      statement_date_range: 'Integration test',
+      bank_transactions_count: count,
+      ynab_transactions_count: 0,
+      auto_matched: 0,
+      suggested_matches: 0,
+      unmatched_bank: count,
+      unmatched_ynab: 0,
+      current_cleared_balance: clearedDollars,
+      target_statement_balance: statementBalance,
+      discrepancy: totalDelta,
+      discrepancy_explanation: 'Synthetic integration delta',
+    },
+    auto_matches: [],
+    suggested_matches: [],
+    unmatched_bank: unmatchedBank,
+    unmatched_ynab: [],
+    balance_info: {
+      current_cleared: clearedDollars,
+      current_uncleared: snapshot.uncleared_balance / 1000,
+      current_total: snapshot.balance / 1000,
+      target_statement: statementBalance,
+      discrepancy: totalDelta,
+      on_track: false,
+    },
+    next_steps: [],
+    insights: [],
+  } as const;
+
+  const params = {
+    budget_id: budgetId,
+    account_id: account.id,
+    csv_data: 'Date,Description,Amount',
+    statement_balance: statementBalance,
+    statement_date: today,
+    date_tolerance_days: 1,
+    amount_tolerance_cents: 1,
+    auto_match_threshold: 90,
+    suggestion_threshold: 60,
+    auto_create_transactions: true,
+    auto_update_cleared_status: false,
+    auto_unclear_missing: false,
+    auto_adjust_dates: false,
+    dry_run: false,
+    require_exact_match: true,
+    confidence_threshold: 0.8,
+    max_resolution_attempts: 3,
+    include_structured_data: false,
+  } as const;
+
+  const result = await executeReconciliation({
+    ynabAPI: api,
+    analysis: analysis as any,
+    params: params as any,
+    budgetId,
+    accountId: account.id,
+    initialAccount: snapshot,
+    currencyCode: 'USD',
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        summary: result.summary,
+        bulk: result.bulk_operation_details,
+        actions: result.actions_taken.slice(0, 5),
+      },
+      null,
+      2,
+    ),
+  );
+
+  const ids: string[] = [];
+  for (const action of result.actions_taken) {
+    if (action.type === 'create_transaction' && (action.transaction as any)?.id) {
+      ids.push((action.transaction as any).id);
+    }
+  }
+  for (const id of ids) {
+    await api.transactions.deleteTransaction(budgetId, id);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});