@dizzlkheinz/ynab-mcpb 0.12.2 → 0.15.0

package/dist/tools/reconciliation/executor.js

@@ -1,10 +1,14 @@
 import { createHash } from 'crypto';
-import { toMilli, toMoneyValue, toMoneyValueFromDecimal, addMilli } from '../../utils/money.js';
+import { YNABAPIError } from '../../server/errorHandler.js';
+import { toMilli, toMoneyValue, addMilli } from '../../utils/money.js';
 import { generateCorrelationKey, correlateResults, toCorrelationPayload, } from '../transactionTools.js';
 const MONEY_EPSILON_MILLI = 100;
 const DEFAULT_TOLERANCE_CENTS = 1;
 const CENTS_TO_MILLI = 10;
 const MAX_BULK_CREATE_CHUNK = 100;
+const MAX_BULK_UPDATE_CHUNK = 100;
+const BATCH_DELAY_MS = 200;
+const MAX_MEMO_LENGTH = 500;
 function chunkArray(array, size) {
     if (size <= 0) {
         throw new Error('chunk size must be positive');
@@ -15,6 +19,16 @@ function chunkArray(array, size) {
     }
     return chunks;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function truncateMemo(memo) {
+    if (!memo)
+        return 'Auto-reconciled from bank statement';
+    if (memo.length <= MAX_MEMO_LENGTH)
+        return memo;
+    return memo.substring(0, MAX_MEMO_LENGTH - 3) + '...';
+}
 function generateBulkImportId(accountId, date, amountMilli, payee) {
     const normalizedPayee = (payee ?? '').trim().toLowerCase();
     const raw = `${accountId}|${date}|${amountMilli}|${normalizedPayee}`;
@@ -74,13 +88,13 @@ export async function executeReconciliation(options) {
     let bulkOperationDetails;
     if (params.auto_create_transactions && !balanceAligned) {
         const buildPreparedEntry = (bankTxn) => {
-            const amountMilli = toMilli(bankTxn.amount);
+            const amountMilli = bankTxn.amount;
             const saveTransaction = {
                 account_id: accountId,
                 amount: amountMilli,
                 date: bankTxn.date,
                 payee_name: bankTxn.payee ?? undefined,
-                memo: bankTxn.memo ?? 'Auto-reconciled from bank statement',
+                memo: truncateMemo(bankTxn.memo),
                 cleared: 'cleared',
                 approved: true,
                 import_id: generateBulkImportId(accountId, bankTxn.date, amountMilli, bankTxn.payee),
@@ -139,22 +153,27 @@ export async function executeReconciliation(options) {
                     recordAlignmentIfNeeded(trigger);
                 }
                 catch (error) {
+                    const ynabError = normalizeYnabError(error);
                     if (bulkOperationDetails) {
                         bulkOperationDetails.transaction_failures += 1;
                     }
-                    const failureReason = error instanceof Error ? error.message : 'Unknown error occurred';
+                    const failureReason = ynabError.message || 'Unknown error occurred';
+                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
                     const failureAction = {
                         type: 'create_transaction_failed',
                         transaction: entry.saveTransaction,
                         reason: options.fallbackError
-                            ? `Bulk fallback failed for ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason})`
-                            : `Failed to create transaction ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason})`,
+                            ? `Bulk fallback failed for ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason}${statusSuffix})`
+                            : `Failed to create transaction ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason}${statusSuffix})`,
                         correlation_key: entry.correlationKey,
                     };
                     if (options.chunkIndex !== undefined) {
                         failureAction.bulk_chunk_index = options.chunkIndex;
                     }
                     actions_taken.push(failureAction);
+                    if (shouldPropagateYnabError(ynabError)) {
+                        throw attachStatusToError(ynabError, error);
+                    }
                 }
             }
             if (bulkOperationDetails && options.fallbackError && sequentialAttempts > 0) {
@@ -280,15 +299,21 @@ export async function executeReconciliation(options) {
                         bulkOperationDetails.bulk_successes += 1;
                     }
                     catch (error) {
-                        bulkOperationDetails.sequential_fallbacks += 1;
+                        const ynabError = normalizeYnabError(error);
+                        const failureReason = ynabError.message || 'unknown error';
                         bulkOperationDetails.bulk_chunk_failures += 1;
+                        if (shouldPropagateYnabError(ynabError)) {
+                            bulkOperationDetails.transaction_failures += chunk.length;
+                            throw attachStatusToError(ynabError, error);
+                        }
+                        bulkOperationDetails.sequential_fallbacks += 1;
                         actions_taken.push({
                             type: 'bulk_create_fallback',
                             transaction: null,
-                            reason: `Bulk chunk #${chunkIndex} failed (${error instanceof Error ? error.message : 'unknown error'}) - falling back to sequential creation`,
+                            reason: `Bulk chunk #${chunkIndex} failed (${failureReason}${ynabError.status ? ` (HTTP ${ynabError.status})` : ''}) - falling back to sequential creation`,
                             bulk_chunk_index: chunkIndex,
                         });
-                        await processSequentialEntries(chunk, { chunkIndex, fallbackError: error });
+                        await processSequentialEntries(chunk, { chunkIndex, fallbackError: ynabError });
                     }
                 }
             }
@@ -306,13 +331,16 @@ export async function executeReconciliation(options) {
             const flags = computeUpdateFlags(match, params);
             if (!flags.needsClearedUpdate && !flags.needsDateUpdate)
                 continue;
-            if (!match.ynab_transaction)
+            if (!match.ynabTransaction)
                 continue;
             const updatePayload = {
-                id: match.ynab_transaction.id,
+                id: match.ynabTransaction.id,
             };
+            if (match.ynabTransaction.memo) {
+                updatePayload.memo = truncateMemo(match.ynabTransaction.memo);
+            }
             if (flags.needsDateUpdate) {
-                updatePayload.date = match.bank_transaction.date;
+                updatePayload.date = match.bankTransaction.date;
             }
             if (flags.needsClearedUpdate) {
                 updatePayload.cleared = 'cleared';
@@ -324,15 +352,15 @@ export async function executeReconciliation(options) {
                 actions_taken.push({
                     type: 'update_transaction',
                     transaction: {
-                        transaction_id: match.ynab_transaction.id,
-                        new_date: flags.needsDateUpdate ? match.bank_transaction.date : undefined,
+                        transaction_id: match.ynabTransaction.id,
+                        new_date: flags.needsDateUpdate ? match.bankTransaction.date : undefined,
                         cleared: flags.needsClearedUpdate ? 'cleared' : undefined,
                     },
                     reason: `Would update transaction: ${updateReason(match, flags, currencyCode)}`,
                 });
                 if (flags.needsClearedUpdate) {
-                    applyClearedDelta(match.ynab_transaction.amount);
-                    if (recordAlignmentIfNeeded(`clearing ${match.ynab_transaction.id ?? 'transaction'} (dry run)`)) {
+                    applyClearedDelta(match.ynabTransaction.amount);
+                    if (recordAlignmentIfNeeded(`clearing ${match.ynabTransaction.id ?? 'transaction'} (dry run)`)) {
                         break;
                     }
                 }
@@ -342,34 +370,75 @@ export async function executeReconciliation(options) {
                 if (flags.needsDateUpdate)
                     summary.dates_adjusted += 1;
                 if (flags.needsClearedUpdate) {
-                    applyClearedDelta(match.ynab_transaction.amount);
-                    if (recordAlignmentIfNeeded(`clearing ${match.ynab_transaction.id}`)) {
+                    applyClearedDelta(match.ynabTransaction.amount);
+                    if (recordAlignmentIfNeeded(`clearing ${match.ynabTransaction.id}`)) {
                         break;
                     }
                 }
             }
         }
         if (!params.dry_run && transactionsToUpdate.length > 0) {
-            const response = await ynabAPI.transactions.updateTransactions(budgetId, {
-                transactions: transactionsToUpdate,
-            });
-            const updatedTransactions = response.data.transactions ?? [];
-            summary.transactions_updated += updatedTransactions.length;
-            for (const updatedTransaction of updatedTransactions) {
-                const match = orderedAutoMatches.find((m) => m.ynab_transaction?.id === updatedTransaction.id);
-                const flags = match
-                    ? computeUpdateFlags(match, params)
-                    : { needsClearedUpdate: false, needsDateUpdate: false };
-                actions_taken.push({
-                    type: 'update_transaction',
-                    transaction: updatedTransaction,
-                    reason: `Updated transaction: ${match ? updateReason(match, flags, currencyCode) : 'cleared'}`,
-                });
+            const updateChunks = chunkArray(transactionsToUpdate, MAX_BULK_UPDATE_CHUNK);
+            for (let chunkIdx = 0; chunkIdx < updateChunks.length; chunkIdx++) {
+                const chunk = updateChunks[chunkIdx];
+                try {
+                    const response = await ynabAPI.transactions.updateTransactions(budgetId, {
+                        transactions: chunk,
+                    });
+                    const updatedTransactions = response.data.transactions ?? [];
+                    summary.transactions_updated += updatedTransactions.length;
+                    for (const updatedTransaction of updatedTransactions) {
+                        const match = orderedAutoMatches.find((m) => m.ynabTransaction?.id === updatedTransaction.id);
+                        const flags = match
+                            ? computeUpdateFlags(match, params)
+                            : { needsClearedUpdate: false, needsDateUpdate: false };
+                        actions_taken.push({
+                            type: 'update_transaction',
+                            transaction: updatedTransaction,
+                            reason: `Updated transaction: ${match ? updateReason(match, flags, currencyCode) : 'cleared'}`,
+                        });
+                    }
+                    accountSnapshotDirty = true;
+                }
+                catch (error) {
+                    const ynabError = normalizeYnabError(error);
+                    const failureReason = ynabError.message || 'Unknown error occurred';
+                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
+                    actions_taken.push({
+                        type: 'batch_update_failed',
+                        transaction: null,
+                        reason: `Failed to update chunk ${chunkIdx + 1}/${updateChunks.length} (${chunk.length} transaction(s)): ${failureReason}${statusSuffix}`,
+                    });
+                    if (shouldPropagateYnabError(ynabError)) {
+                        throw attachStatusToError(ynabError, error);
+                    }
+                }
+                if (chunkIdx < updateChunks.length - 1) {
+                    await sleep(BATCH_DELAY_MS);
+                }
             }
-            accountSnapshotDirty = true;
         }
     }
     const shouldRunSanityPass = params.auto_unclear_missing && !balanceAligned;
+    actions_taken.push({
+        type: 'diagnostic_step3_entry',
+        transaction: null,
+        reason: `STEP 3 diagnostics: auto_unclear_missing=${params.auto_unclear_missing}, balanceAligned=${balanceAligned}, shouldRunSanityPass=${shouldRunSanityPass}, orderedUnmatchedYNAB.length=${orderedUnmatchedYNAB.length}`,
+    });
+    if (orderedUnmatchedYNAB.length > 0) {
+        const unmatchedDetails = orderedUnmatchedYNAB.slice(0, 10).map((t) => ({
+            id: t.id,
+            date: t.date,
+            cleared: t.cleared,
+            amount: formatDisplay(t.amount, currencyCode),
+            payee: t.payee ?? 'Unknown',
+        }));
+        actions_taken.push({
+            type: 'diagnostic_unmatched_ynab',
+            transaction: { unmatched_transactions: unmatchedDetails },
+            reason: `First ${Math.min(10, orderedUnmatchedYNAB.length)} unmatched YNAB transactions (cleared status and amounts)`,
+        });
+    }
     if (shouldRunSanityPass) {
         const transactionsToUnclear = [];
         for (const ynabTxn of orderedUnmatchedYNAB) {
@@ -401,19 +470,97 @@ export async function executeReconciliation(options) {
             }
         }
         if (!params.dry_run && transactionsToUnclear.length > 0) {
-            const response = await ynabAPI.transactions.updateTransactions(budgetId, {
-                transactions: transactionsToUnclear,
+            const unclearChunks = chunkArray(transactionsToUnclear, MAX_BULK_UPDATE_CHUNK);
+            for (let chunkIdx = 0; chunkIdx < unclearChunks.length; chunkIdx++) {
+                const chunk = unclearChunks[chunkIdx];
+                try {
+                    const response = await ynabAPI.transactions.updateTransactions(budgetId, {
+                        transactions: chunk,
+                    });
+                    const updatedTransactions = response.data.transactions ?? [];
+                    summary.transactions_updated += updatedTransactions.length;
+                    for (const updatedTransaction of updatedTransactions) {
+                        actions_taken.push({
+                            type: 'update_transaction',
+                            transaction: updatedTransaction,
+                            reason: `Marked transaction ${updatedTransaction.id} as uncleared - not found on statement`,
+                        });
+                    }
+                    accountSnapshotDirty = true;
+                }
+                catch (error) {
+                    const ynabError = normalizeYnabError(error);
+                    const failureReason = ynabError.message || 'Unknown error occurred';
+                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
+                    actions_taken.push({
+                        type: 'batch_unclear_failed',
+                        transaction: null,
+                        reason: `Failed to unclear chunk ${chunkIdx + 1}/${unclearChunks.length} (${chunk.length} transaction(s)): ${failureReason}${statusSuffix}`,
+                    });
+                    if (shouldPropagateYnabError(ynabError)) {
+                        throw attachStatusToError(ynabError, error);
+                    }
+                }
+                if (chunkIdx < unclearChunks.length - 1) {
+                    await sleep(BATCH_DELAY_MS);
+                }
+            }
+        }
+    }
+    if (balanceAligned && !params.dry_run) {
+        const transactionsToReconcile = [];
+        for (const match of orderedAutoMatches) {
+            if (!match.ynabTransaction)
+                continue;
+            if (match.ynabTransaction.cleared === 'reconciled')
+                continue;
+            transactionsToReconcile.push({
+                id: match.ynabTransaction.id,
+                cleared: 'reconciled',
             });
-            const updatedTransactions = response.data.transactions ?? [];
-            summary.transactions_updated += updatedTransactions.length;
-            for (const updatedTransaction of updatedTransactions) {
-                actions_taken.push({
-                    type: 'update_transaction',
-                    transaction: updatedTransaction,
-                    reason: `Marked transaction ${updatedTransaction.id} as uncleared - not found on statement`,
-                });
+        }
+        if (transactionsToReconcile.length > 0) {
+            const reconcileChunks = chunkArray(transactionsToReconcile, MAX_BULK_UPDATE_CHUNK);
+            for (let chunkIdx = 0; chunkIdx < reconcileChunks.length; chunkIdx++) {
+                const chunk = reconcileChunks[chunkIdx];
+                try {
+                    const response = await ynabAPI.transactions.updateTransactions(budgetId, {
+                        transactions: chunk,
+                    });
+                    const reconciledTransactions = response.data.transactions ?? [];
+                    summary.transactions_updated += reconciledTransactions.length;
+                    for (const reconciledTransaction of reconciledTransactions) {
+                        const match = orderedAutoMatches.find((m) => m.ynabTransaction?.id === reconciledTransaction.id);
+                        actions_taken.push({
+                            type: 'update_transaction',
+                            transaction: reconciledTransaction,
+                            reason: `Marked as reconciled: ${match?.bankTransaction.payee ?? 'transaction'} (${formatDisplay(reconciledTransaction.amount, currencyCode)})`,
+                        });
+                    }
+                    accountSnapshotDirty = true;
+                }
+                catch (error) {
+                    const ynabError = normalizeYnabError(error);
+                    const failureReason = ynabError.message || 'Unknown error occurred';
+                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
+                    actions_taken.push({
+                        type: 'batch_reconcile_failed',
+                        transaction: null,
+                        reason: `Failed to reconcile chunk ${chunkIdx + 1}/${reconcileChunks.length} (${chunk.length} transaction(s)): ${failureReason}${statusSuffix}`,
+                    });
+                    if (shouldPropagateYnabError(ynabError)) {
+                        throw attachStatusToError(ynabError, error);
+                    }
+                }
+                if (chunkIdx < reconcileChunks.length - 1) {
+                    await sleep(BATCH_DELAY_MS);
+                }
             }
-            accountSnapshotDirty = true;
+            actions_taken.push({
+                type: 'reconciliation_complete',
+                transaction: null,
+                reason: `Marked ${transactionsToReconcile.length} matched transaction(s) as reconciled - balance aligned within tolerance`,
+            });
         }
     }
     let balance_reconciliation;
@@ -456,12 +603,92 @@ export async function executeReconciliation(options) {
     }
     return result;
 }
+const FATAL_YNAB_STATUS_CODES = new Set([400, 401, 403, 404, 429, 500, 503]);
+export function normalizeYnabError(error) {
+    const parseStatus = (value) => {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value === 'string') {
+            const numeric = Number(value);
+            if (Number.isFinite(numeric))
+                return numeric;
+        }
+        return undefined;
+    };
+    if (error instanceof Error) {
+        const status = parseStatus(error.status) ??
+            parseStatus(error.response?.status);
+        const detailSource = error.detail;
+        const detail = typeof detailSource === 'string' && detailSource.trim().length > 0 ? detailSource : undefined;
+        const result = {
+            name: error.name,
+            message: error.message || 'Unknown error occurred',
+        };
+        if (status !== undefined)
+            result.status = status;
+        if (detail !== undefined)
+            result.detail = detail;
+        return result;
+    }
+    if (error && typeof error === 'object') {
+        const errObj = error.error ?? error;
+        const status = parseStatus(errObj.id ?? errObj.status);
+        const detailCandidate = errObj.detail ??
+            errObj.message ??
+            errObj.name;
+        const detail = typeof detailCandidate === 'string' && detailCandidate.trim().length > 0
+            ? detailCandidate
+            : undefined;
+        const message = detail ??
+            (typeof errObj === 'string' && errObj.trim().length > 0 ? errObj : 'Unknown error occurred');
+        const name = typeof errObj.name === 'string'
+            ? errObj.name
+            : undefined;
+        const result = { message };
+        if (status !== undefined)
+            result.status = status;
+        if (name !== undefined)
+            result.name = name;
+        if (detail !== undefined)
+            result.detail = detail;
+        return result;
+    }
+    if (typeof error === 'string') {
+        return { message: error };
+    }
+    return { message: 'Unknown error occurred' };
+}
+export function shouldPropagateYnabError(error) {
+    return error.status !== undefined && FATAL_YNAB_STATUS_CODES.has(error.status);
+}
+function attachStatusToError(error, originalError) {
+    const message = error.message || 'YNAB API error';
+    const isKnownCode = error.status === 400 ||
+        error.status === 401 ||
+        error.status === 403 ||
+        error.status === 404 ||
+        error.status === 429 ||
+        error.status === 500;
+    if (isKnownCode) {
+        return new YNABAPIError(error.status, message, originalError);
+    }
+    const statusFragment = error.status ? ` (HTTP ${error.status})` : '';
+    const detailFragment = error.detail && !message.includes(error.detail) ? ` (${error.detail})` : '';
+    const err = new Error(`${message}${statusFragment}${detailFragment}`);
+    if (error.status !== undefined) {
+        err.status = error.status;
+    }
+    if (error.name) {
+        err.name = error.name;
+    }
+    return err;
+}
 function formatDisplay(amount, currency) {
-    return toMoneyValueFromDecimal(amount, currency).value_display;
+    return toMoneyValue(amount, currency).value_display;
 }
 function computeUpdateFlags(match, params) {
-    const ynabTxn = match.ynab_transaction;
-    const bankTxn = match.bank_transaction;
+    const ynabTxn = match.ynabTransaction;
+    const bankTxn = match.bankTransaction;
     if (!ynabTxn) {
         return { needsClearedUpdate: false, needsDateUpdate: false };
     }
@@ -475,7 +702,7 @@ function updateReason(match, flags, _currency) {
         parts.push('marked as cleared');
     }
     if (flags.needsDateUpdate) {
-        parts.push(`date adjusted to ${match.bank_transaction.date}`);
+        parts.push(`date adjusted to ${match.bankTransaction.date}`);
     }
     return parts.join(', ');
 }
@@ -596,7 +823,7 @@ function sortByDateDescending(items) {
     return [...items].sort((a, b) => compareDates(b.date, a.date));
 }
 function sortMatchesByBankDateDescending(matches) {
-    return [...matches].sort((a, b) => compareDates(b.bank_transaction.date, a.bank_transaction.date));
+    return [...matches].sort((a, b) => compareDates(b.bankTransaction.date, a.bankTransaction.date));
 }
 function compareDates(dateA, dateB) {
     return toChronoValue(dateA) - toChronoValue(dateB);

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

@@ -11,16 +11,16 @@ export declare const ReconcileAccountSchema: z.ZodObject<{
     account_id: z.ZodString;
     csv_file_path: z.ZodOptional<z.ZodString>;
     csv_data: z.ZodOptional<z.ZodString>;
-    csv_format: z.ZodDefault<z.ZodOptional<z.ZodObject<{
-        date_column: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    csv_format: z.ZodOptional<z.ZodObject<{
+        date_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         amount_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         debit_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         credit_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-        description_column: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
-        date_format: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        has_header: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-        delimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    }, z.core.$strict>>>;
+        description_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        date_format: z.ZodOptional<z.ZodString>;
+        has_header: z.ZodOptional<z.ZodBoolean>;
+        delimiter: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     statement_balance: z.ZodNumber;
     statement_start_date: z.ZodOptional<z.ZodString>;
     statement_end_date: z.ZodOptional<z.ZodString>;