@dizzlkheinz/ynab-mcpb 0.12.2 → 0.15.0

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/tools/transactionTools.d.ts

@@ -58,13 +58,13 @@ export type CreateTransactionParams = z.infer<typeof CreateTransactionSchema>;
 type BulkTransactionInput = Omit<CreateTransactionParams, 'budget_id' | 'dry_run' | 'subtransactions'>;
 export declare const CreateTransactionsSchema: z.ZodObject<{
     budget_id: z.ZodString;
-    transactions: z.ZodArray<z.ZodPipe<z.ZodObject<{
+    transactions: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
         cleared: z.ZodOptional<z.ZodEnum<{
             cleared: "cleared";
             uncleared: "uncleared";
             reconciled: "reconciled";
         }>>;
-        date: z.ZodString;
         amount: z.ZodNumber;
         memo: z.ZodOptional<z.ZodString>;
         approved: z.ZodOptional<z.ZodBoolean>;
@@ -81,21 +81,7 @@ export declare const CreateTransactionsSchema: z.ZodObject<{
         category_id: z.ZodOptional<z.ZodString>;
         import_id: z.ZodOptional<z.ZodString>;
         payee_name: z.ZodOptional<z.ZodString>;
-        subtransactions: z.ZodOptional<z.ZodAny>;
-    }, z.core.$strict>, z.ZodTransform<BulkTransactionInput, {
-        date: string;
-        amount: number;
-        account_id: string;
-        cleared?: "cleared" | "uncleared" | "reconciled" | undefined;
-        memo?: string | undefined;
-        approved?: boolean | undefined;
-        flag_color?: "red" | "orange" | "yellow" | "green" | "blue" | "purple" | undefined;
-        payee_id?: string | undefined;
-        category_id?: string | undefined;
-        import_id?: string | undefined;
-        payee_name?: string | undefined;
-        subtransactions?: any;
-    }>>>;
+    }, z.core.$strict>>;
     dry_run: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type CreateTransactionsParams = z.infer<typeof CreateTransactionsSchema>;

package/dist/tools/transactionTools.js

@@ -161,23 +161,7 @@ const BulkTransactionInputSchemaBase = CreateTransactionSchema.pick({
     flag_color: true,
     import_id: true,
 });
-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) => {
-    const { subtransactions, ...rest } = data;
-    return rest;
-});
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
 export const CreateTransactionsSchema = z
     .object({
     budget_id: z.string().min(1, 'Budget ID is required'),
@@ -541,6 +525,10 @@ export async function handleListTransactions(ynabAPI, deltaFetcherOrParams, mayb
                             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/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/dist/utils/baseError.d.ts

@@ -0,0 +1,3 @@
+export declare class BaseError extends Error {
+    constructor(message: string);
+}

package/dist/utils/baseError.js

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

package/dist/utils/errors.d.ts

@@ -0,0 +1,13 @@
+export { BaseError } from './baseError.js';
+export { ValidationError } from './validationError.js';
+import { BaseError } from './baseError.js';
+export declare class ConfigurationError extends BaseError {
+}
+export declare class AuthenticationError extends BaseError {
+}
+export declare class YNABRequestError extends BaseError {
+    status: number;
+    statusText: string;
+    ynabErrorId?: string | undefined;
+    constructor(status: number, statusText: string, ynabErrorId?: string | undefined);
+}

package/dist/utils/errors.js

@@ -0,0 +1,15 @@
+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(status, statusText, ynabErrorId) {
+        super(`YNAB API request failed: ${status} ${statusText}${ynabErrorId ? ` (Error ID: ${ynabErrorId})` : ''}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.ynabErrorId = ynabErrorId;
+    }
+}

package/dist/utils/validationError.d.ts

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

package/dist/utils/validationError.js

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