@dizzlkheinz/ynab-mcpb 0.13.1 → 0.15.1

package/dist/tools/reconciliation/recommendationEngine.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'crypto';
-import { toMoneyValueFromDecimal, fromMilli, toMilli } from '../../utils/money.js';
+import { toMoneyValue, toMoneyValueFromDecimal, fromMilli } from '../../utils/money.js';
 const RECOMMENDATION_VERSION = '1.0';
 const CONFIDENCE = {
     CREATE_EXACT_MATCH: 0.95,
@@ -33,15 +33,15 @@ function processInsight(insight, context) {
     }
 }
 function createSuggestedMatchRecommendation(match, context) {
-    const bankTxn = match.bank_transaction;
-    if (match.ynab_transaction && match.confidence !== 'none') {
+    const bankTxn = match.bankTransaction;
+    if (match.ynabTransaction && match.confidence !== 'none') {
         return {
             id: randomUUID(),
             action_type: 'review_duplicate',
             priority: 'high',
-            confidence: Math.max(0, Math.min(1, match.confidence_score / 100)),
+            confidence: Math.max(0, Math.min(1, match.confidenceScore / 100)),
             message: `Review possible match: ${bankTxn.payee}`,
-            reason: match.match_reason,
+            reason: match.matchReason,
             estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
             account_id: context.account_id,
             metadata: {
@@ -49,20 +49,20 @@ function createSuggestedMatchRecommendation(match, context) {
                 created_at: new Date().toISOString(),
             },
             parameters: {
-                candidate_ids: [match.ynab_transaction.id],
+                candidate_ids: [match.ynabTransaction.id],
                 bank_transaction: bankTxn,
-                suggested_match_id: match.ynab_transaction.id,
+                suggested_match_id: match.ynabTransaction.id,
             },
         };
     }
-    const isCombinationMatch = match.match_reason === 'combination_match' || (match.candidates?.length ?? 0) > 1;
+    const isCombinationMatch = (match.candidates?.length ?? 0) > 1;
     if (isCombinationMatch) {
         return createCombinationReviewRecommendation(match, context);
     }
     const parameters = {
         account_id: context.account_id,
         date: bankTxn.date,
-        amount: toMilli(bankTxn.amount),
+        amount: bankTxn.amount,
         payee_name: bankTxn.payee,
         cleared: 'cleared',
         approved: true,
@@ -77,7 +77,7 @@ function createSuggestedMatchRecommendation(match, context) {
         confidence: CONFIDENCE.CREATE_EXACT_MATCH,
         message: `Create transaction for ${bankTxn.payee}`,
         reason: `This transaction exactly matches your discrepancy`,
-        estimated_impact: toMoneyValueFromDecimal(bankTxn.amount, context.analysis.balance_info.current_cleared.currency),
+        estimated_impact: toMoneyValue(bankTxn.amount, context.analysis.balance_info.current_cleared.currency),
         account_id: context.account_id,
         metadata: {
             version: RECOMMENDATION_VERSION,
@@ -87,7 +87,7 @@ function createSuggestedMatchRecommendation(match, context) {
     };
 }
 function createCombinationReviewRecommendation(match, context) {
-    const bankTxn = match.bank_transaction;
+    const bankTxn = match.bankTransaction;
     const candidateIds = match.candidates?.map((candidate) => candidate.ynab_transaction.id) ?? [];
     const candidateTotalAmount = match.candidates?.reduce((sum, candidate) => {
         const amount = candidate.ynab_transaction.amount;
@@ -110,7 +110,7 @@ function createCombinationReviewRecommendation(match, context) {
         metadata: {
             version: RECOMMENDATION_VERSION,
             created_at: new Date().toISOString(),
-            bank_transaction_amount: toMoneyValueFromDecimal(bankTxn.amount, context.analysis.balance_info.current_cleared.currency),
+            bank_transaction_amount: toMoneyValue(bankTxn.amount, context.analysis.balance_info.current_cleared.currency),
             candidate_total_amount: toMoneyValueFromDecimal(candidateTotalAmount, context.analysis.balance_info.current_cleared.currency),
             candidate_count: match.candidates?.length ?? 0,
         },
@@ -125,8 +125,8 @@ function createCombinationReviewRecommendation(match, context) {
                 ...candidateIds.map((id) => ({
                     source: 'ynab',
                     id,
-                    description: match.candidates?.find((c) => c.ynab_transaction.id === id)?.ynab_transaction
-                        .payee_name ?? 'Unknown',
+                    description: match.candidates?.find((c) => c.ynab_transaction.id === id)?.ynab_transaction.payee ??
+                        'Unknown',
                 })),
             ],
         },
@@ -205,7 +205,11 @@ function processUnmatchedTransactions(context) {
     for (const bankTxn of context.analysis.unmatched_bank) {
         recommendations.push(createUnmatchedBankRecommendation(bankTxn, context));
     }
-    for (const match of context.analysis.suggested_matches) {
+    const matchesForReview = [
+        ...context.analysis.suggested_matches,
+        ...context.analysis.auto_matches,
+    ];
+    for (const match of matchesForReview) {
         recommendations.push(createSuggestedMatchRecommendation(match, context));
     }
     for (const ynabTxn of context.analysis.unmatched_ynab) {
@@ -219,7 +223,7 @@ function createUnmatchedBankRecommendation(txn, context) {
     const parameters = {
         account_id: context.account_id,
         date: txn.date,
-        amount: toMilli(txn.amount),
+        amount: txn.amount,
         payee_name: txn.payee,
         cleared: 'cleared',
         approved: true,
@@ -234,7 +238,7 @@ function createUnmatchedBankRecommendation(txn, context) {
         confidence: CONFIDENCE.UNMATCHED_BANK,
         message: `Create missing transaction: ${txn.payee}`,
         reason: 'Transaction appears on bank statement but not in YNAB',
-        estimated_impact: toMoneyValueFromDecimal(txn.amount, context.analysis.balance_info.current_cleared.currency),
+        estimated_impact: toMoneyValue(txn.amount, context.analysis.balance_info.current_cleared.currency),
         account_id: context.account_id,
         metadata: {
             version: RECOMMENDATION_VERSION,
@@ -249,7 +253,7 @@ function createUpdateClearedRecommendation(txn, context) {
         action_type: 'update_cleared',
         priority: 'low',
         confidence: CONFIDENCE.UPDATE_CLEARED,
-        message: `Mark transaction as cleared: ${txn.payee_name || 'Unknown'}`,
+        message: `Mark transaction as cleared: ${txn.payee || 'Unknown'}`,
         reason: 'Transaction exists in YNAB but not yet cleared',
         estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
         account_id: context.account_id,

package/dist/tools/reconciliation/reportFormatter.js

@@ -81,12 +81,13 @@ function formatBankTransactionLine(txn) {
     return `   ${txn.date} - ${txn.payee.substring(0, 40).padEnd(40)} ${amountStr}`;
 }
 function formatSuggestedMatchLine(match) {
-    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)`;
 }
-function formatAmount(amount) {
+function formatAmount(amountMilli) {
+    const amount = amountMilli / 1000;
     const sign = amount >= 0 ? '+' : '-';
     const absAmount = Math.abs(amount);
     return `${sign}$${absAmount.toFixed(2)}`.padStart(10);
@@ -198,13 +199,13 @@ export function formatTransactionList(transactions, maxItems = 10) {
     const lines = [];
     const toShow = transactions.slice(0, maxItems);
     for (const txn of toShow) {
-        if ('payee' in txn) {
-            lines.push(formatBankTransactionLine(txn));
+        if ('cleared' in txn) {
+            const ynabTxn = txn;
+            const payee = ynabTxn.payee_name ?? ynabTxn.payee ?? 'Unknown';
+            lines.push(`   ${ynabTxn.date} - ${payee.substring(0, 40).padEnd(40)} ${formatAmount(ynabTxn.amount)}`);
         }
         else {
-            const amount = txn.amount / 1000;
-            const payee = txn.payee_name ?? 'Unknown';
-            lines.push(`   ${txn.date} - ${payee.substring(0, 40).padEnd(40)} ${formatAmount(amount)}`);
+            lines.push(formatBankTransactionLine(txn));
         }
     }
     if (transactions.length > maxItems) {

package/dist/tools/reconciliation/signDetector.d.ts

@@ -0,0 +1,2 @@
+import type { BankTransaction, NormalizedYNABTransaction } from '../../types/reconciliation.js';
+export declare function detectSignInversion(bankTransactions: BankTransaction[], ynabTransactions: NormalizedYNABTransaction[]): boolean;

package/dist/tools/reconciliation/signDetector.js

@@ -0,0 +1,54 @@
+export function detectSignInversion(bankTransactions, ynabTransactions) {
+    if (bankTransactions.length === 0 || ynabTransactions.length === 0) {
+        return false;
+    }
+    const sampleSize = Math.min(20, bankTransactions.length);
+    const sample = bankTransactions.slice(0, sampleSize);
+    const matches = [];
+    for (const bankTxn of sample) {
+        const match = findClosestMatch(bankTxn, ynabTransactions);
+        if (match) {
+            matches.push(match);
+        }
+    }
+    if (matches.length === 0) {
+        return false;
+    }
+    const oppositeSignCount = matches.filter((m) => m.oppositeSign).length;
+    const oppositeSignRatio = oppositeSignCount / matches.length;
+    return oppositeSignRatio > 0.5;
+}
+function findClosestMatch(bankTxn, ynabTransactions) {
+    const bankDate = new Date(bankTxn.date);
+    const bankAbsAmount = Math.abs(bankTxn.amount);
+    let bestMatch = null;
+    let bestScore = 0;
+    for (const ynabTxn of ynabTransactions) {
+        const ynabDate = new Date(ynabTxn.date);
+        const ynabAbsAmount = Math.abs(ynabTxn.amount);
+        const amountDiff = Math.abs(bankAbsAmount - ynabAbsAmount);
+        const amountTolerance = 100;
+        if (amountDiff > amountTolerance) {
+            continue;
+        }
+        const daysDiff = Math.abs(bankDate.getTime() - ynabDate.getTime()) / (1000 * 60 * 60 * 24);
+        if (daysDiff > 7) {
+            continue;
+        }
+        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;
+            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/dist/tools/reconciliation/types.d.ts

@@ -1,23 +1,8 @@
 import type { MoneyValue } from '../../utils/money.js';
+import type { BankTransaction as CanonicalBankTransaction, NormalizedYNABTransaction as CanonicalYNABTransaction } from '../../types/reconciliation.js';
+export type BankTransaction = CanonicalBankTransaction;
+export type YNABTransaction = CanonicalYNABTransaction;
 export type MatchConfidence = 'high' | 'medium' | 'low' | 'none';
-export interface BankTransaction {
-    id: string;
-    date: string;
-    amount: number;
-    payee: string;
-    memo?: string;
-    original_csv_row: number;
-}
-export interface YNABTransaction {
-    id: string;
-    date: string;
-    amount: number;
-    payee_name: string | null;
-    category_name: string | null;
-    cleared: 'cleared' | 'uncleared' | 'reconciled';
-    approved: boolean;
-    memo?: string | null;
-}
 export interface MatchCandidate {
     ynab_transaction: YNABTransaction;
     confidence: number;
@@ -25,14 +10,14 @@ export interface MatchCandidate {
     explanation: string;
 }
 export interface TransactionMatch {
-    bank_transaction: BankTransaction;
-    ynab_transaction?: YNABTransaction;
+    bankTransaction: BankTransaction;
+    ynabTransaction?: YNABTransaction;
     candidates?: MatchCandidate[];
     confidence: MatchConfidence;
-    confidence_score: number;
-    match_reason: string;
-    top_confidence?: number;
-    action_hint?: string;
+    confidenceScore: number;
+    matchReason: string;
+    topConfidence?: number;
+    actionHint?: string;
     recommendation?: string;
 }
 export interface BalanceInfo {
@@ -90,19 +75,20 @@ export interface ReconciliationAction {
     metadata?: Record<string, unknown>;
 }
 export interface MatchingConfig {
+    weights: {
+        amount: number;
+        date: number;
+        payee: number;
+    };
+    amountToleranceMilliunits: number;
     dateToleranceDays: number;
-    amountToleranceCents: number;
-    descriptionSimilarityThreshold: number;
     autoMatchThreshold: number;
-    suggestionThreshold: number;
+    suggestedMatchThreshold: number;
+    minimumCandidateScore: number;
+    exactAmountBonus: number;
+    exactDateBonus: number;
+    exactPayeeBonus: number;
 }
-export declare const DEFAULT_MATCHING_CONFIG: {
-    dateToleranceDays: number;
-    amountToleranceCents: number;
-    descriptionSimilarityThreshold: number;
-    autoMatchThreshold: number;
-    suggestionThreshold: number;
-};
 export interface ParsedCSVData {
     transactions: BankTransaction[];
     format_detected: string;

package/dist/tools/reconciliation/types.js

@@ -1,7 +1 @@
-export const DEFAULT_MATCHING_CONFIG = {
-    dateToleranceDays: 2,
-    amountToleranceCents: 1,
-    descriptionSimilarityThreshold: 0.8,
-    autoMatchThreshold: 90,
-    suggestionThreshold: 60,
-};
+export {};

package/dist/tools/reconciliation/ynabAdapter.d.ts

@@ -0,0 +1,4 @@
+import type * as ynab from 'ynab';
+import type { NormalizedYNABTransaction } from '../../types/reconciliation.js';
+export declare function normalizeYNABTransaction(txn: ynab.TransactionDetail): NormalizedYNABTransaction;
+export declare function normalizeYNABTransactions(txns: ynab.TransactionDetail[]): NormalizedYNABTransaction[];

package/dist/tools/reconciliation/ynabAdapter.js

@@ -0,0 +1,15 @@
+export function normalizeYNABTransaction(txn) {
+    return {
+        id: txn.id,
+        date: txn.date,
+        amount: txn.amount,
+        payee: txn.payee_name ?? null,
+        memo: txn.memo ?? null,
+        categoryName: txn.category_name ?? null,
+        cleared: txn.cleared,
+        approved: txn.approved,
+    };
+}
+export function normalizeYNABTransactions(txns) {
+    return txns.map(normalizeYNABTransaction);
+}

package/dist/types/reconciliation.d.ts

@@ -0,0 +1,24 @@
+export interface BankTransaction {
+    id: string;
+    date: string;
+    amount: number;
+    payee: string;
+    memo?: string;
+    sourceRow: number;
+    raw: {
+        date: string;
+        amount: string;
+        description: string;
+    };
+    warnings?: string[];
+}
+export interface NormalizedYNABTransaction {
+    id: string;
+    date: string;
+    amount: number;
+    payee: string | null;
+    memo: string | null;
+    categoryName: string | null;
+    cleared: 'cleared' | 'uncleared' | 'reconciled';
+    approved: boolean;
+}

package/dist/types/reconciliation.js

@@ -0,0 +1 @@
+export {};

package/docs/guides/ARCHITECTURE.md

@@ -1,24 +1,23 @@
 # YNAB MCP Server Architecture
 
-This guide explains the v0.8.x modular architecture, core components, and architectural patterns.
+This guide explains the modular architecture, core components, and architectural patterns.
 
 ## Table of Contents
 
-- [v0.8.x Modular Architecture](#v08x-modular-architecture)
+- [Modular Architecture](#modular-architecture)
 - [Core Components](#core-components)
 - [Dependency Injection Pattern](#dependency-injection-pattern)
-- [Developing Tools with v0.8.x](#developing-tools-with-v08x)
+- [Developing Tools](#developing-tools)
 - [Cache Management](#cache-management)
 - [Service Module Patterns](#service-module-patterns)
-- [Migration from v0.7.x](#migration-from-v07x)
 
-## v0.8.x Modular Architecture
+## Modular Architecture
 
-The v0.8.x series introduces a completely refactored architecture that improves maintainability, testability, and performance while maintaining 100% backward compatibility.
+The server uses a modular architecture that improves maintainability, testability, and performance.
 
 ### Architecture Overview
 
-The v0.8.x architecture consists of several key components working together:
+The architecture consists of several key components working together:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -92,10 +91,10 @@ Focused modules handling specific server concerns:
 
 ## Dependency Injection Pattern
 
-The v0.8.x releases adopt explicit dependency injection for better testability and maintainability:
+The architecture uses explicit dependency injection for better testability and maintainability:
 
 ```typescript
-// v0.8.x pattern - explicit dependencies
+// Explicit dependency injection pattern
 class MyService {
   constructor(
     private cacheManager: CacheManager,
@@ -120,11 +119,11 @@ class MyService {
 const myService = new MyService(cacheManager, errorHandler, budgetResolver);
 ```
 
-## Developing Tools with v0.8.x
+## Developing Tools
 
 ### Tool Development Patterns
 
-Creating new tools in v0.8.x follows the Tool Registry pattern for consistency and maintainability.
+Creating new tools follows the Tool Registry pattern for consistency and maintainability.
 
 #### 1. Define Tool Schema
 
@@ -250,7 +249,7 @@ export async function handleMyTool(params: MyToolRequest): Promise<any> {
 
 ### Understanding the Enhanced Cache System
 
-The v0.8.x line introduces a sophisticated caching system designed for performance and observability.
+The server includes a sophisticated caching system designed for performance and observability.
 
 #### Cache Configuration
 
@@ -423,7 +422,7 @@ export async function handleSetDefaultBudget(params: SetDefaultBudgetRequest) {
 
 ### Working with Service Modules
 
-The v0.8.x releases decompose server functionality into focused service modules.
+The server decomposes functionality into focused service modules.
 
 #### Resource Manager
 
@@ -528,122 +527,6 @@ class MyDiagnosticManager extends DiagnosticManager {
 }
 ```
 
-## Migration from v0.7.x
-
-### No Breaking Changes for Users
-
-**Important:** All v0.7.x tool calls, parameters, and responses work identically in v0.8.x. This section is for developers working with the internal architecture.
-
-### Internal API Changes
-
-#### Error Handling Migration
-
-**v0.7.x Pattern:**
-```typescript
-// Direct error throwing
-if (!budgetId) {
-  throw new Error('No budget ID provided');
-}
-```
-
-**v0.8.x Pattern:**
-```typescript
-// Centralized error handling with consistent format
-const result = BudgetResolver.resolveBudgetId(providedId, defaultId);
-if (typeof result !== 'string') {
-  return result; // Returns properly formatted CallToolResult
-}
-```
-
-#### Caching Migration
-
-**v0.7.x Pattern:**
-```typescript
-// Manual cache management
-const cached = cacheManager.get(key);
-if (cached && !isExpired(cached)) {
-  return cached.data;
-}
-
-const result = await apiCall();
-cacheManager.set(key, result, ttl);
-return result;
-```
-
-**v0.8.x Pattern:**
-```typescript
-// Enhanced cache wrapper with observability
-return cacheManager.wrap(key, {
-  ttl: CACHE_TTLS.ACCOUNTS,
-  staleWhileRevalidate: 120000,
-  loader: () => apiCall()
-});
-```
-
-#### Tool Registration Migration
-
-**v0.7.x Pattern:**
-```typescript
-// Direct switch statement in handleCallTool
-case 'my_tool':
-  return withSecurityWrapper(async () => {
-    const validated = MyToolSchema.parse(params);
-    return await handleMyTool(validated);
-  });
-```
-
-**v0.8.x Pattern:**
-```typescript
-// Registry-based registration
-registry.register({
-  name: 'my_tool',
-  description: 'Tool description',
-  inputSchema: MyToolSchema,
-  handler: adapt(handleMyTool),
-  defaultArgumentResolver: resolveBudgetId()
-});
-```
-
-### Testing Pattern Updates
-
-**Enhanced Dependency Injection for Testing:**
-
-```typescript
-// v0.8.x - Mock individual services
-const mockCacheManager = {
-  wrap: vi.fn().mockImplementation((key, options) => options.loader()),
-  getStats: vi.fn().mockReturnValue({ hit_rate: 0.5 })
-};
-
-const mockErrorHandler = {
-  createErrorResponse: vi.fn().mockReturnValue({ success: false })
-};
-
-// Test with mocked dependencies
-const service = new MyService(mockCacheManager, mockErrorHandler);
-```
-
-### Import Path Updates
-
-Most imports remain the same due to barrel exports:
-
-```typescript
-// Still works (barrel export)
-import { handleMyTool } from '../tools/myTool.js';
-
-// New modular imports available
-import { parseCSV } from '../tools/compareTransactions/parser.js';
-import { findMatches } from '../tools/compareTransactions/matcher.js';
-import { formatResults } from '../tools/compareTransactions/formatter.js';
-```
-
-### Performance Improvements to Expect
-
-- **Cache Hit Rate**: 60-80% for repeated operations
-- **Initial Load Time**: Faster due to cache warming
-- **Memory Usage**: More efficient with LRU eviction
-- **Error Response Time**: Faster with pre-formatted responses
-
 ---
 
 For practical development patterns and examples, see [`DEVELOPMENT.md`](DEVELOPMENT.md).