@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/dist/tools/reconciliation/executor.js

@@ -1,6 +1,6 @@
-import { YNABAPIError } from '../../server/errorHandler.js';
-import { toMilli, toMoneyValue, addMilli } from '../../utils/money.js';
-import { generateCorrelationKey, correlateResults, toCorrelationPayload, } from '../transactionTools.js';
+import { YNABAPIError, YNABErrorCode } from "../../server/errorHandler.js";
+import { addMilli, toMilli, toMoneyValue } from "../../utils/money.js";
+import { correlateResults, generateCorrelationKey, toCorrelationPayload, } from "../transactionTools.js";
 const MONEY_EPSILON_MILLI = 100;
 const DEFAULT_TOLERANCE_CENTS = 1;
 const CENTS_TO_MILLI = 10;
@@ -10,7 +10,7 @@ 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');
+        throw new Error("chunk size must be positive");
     }
     const chunks = [];
     for (let i = 0; i < array.length; i += size) {
@@ -23,10 +23,10 @@ function sleep(ms) {
 }
 function truncateMemo(memo) {
     if (!memo)
-        return 'Auto-reconciled from bank statement';
+        return "Auto-reconciled from bank statement";
     if (memo.length <= MAX_MEMO_LENGTH)
         return memo;
-    return memo.substring(0, MAX_MEMO_LENGTH - 3) + '...';
+    return `${memo.substring(0, MAX_MEMO_LENGTH - 3)}...`;
 }
 function parseISODate(dateStr) {
     if (!dateStr)
@@ -46,8 +46,10 @@ function resolveStatementWindow(params, analysisDateRange) {
             window.end = end;
         return window;
     }
-    if (analysisDateRange && analysisDateRange.includes(' to ')) {
-        const [rawStart, rawEnd] = analysisDateRange.split(' to ').map((part) => part.trim());
+    if (analysisDateRange?.includes(" to ")) {
+        const [rawStart, rawEnd] = analysisDateRange
+            .split(" to ")
+            .map((part) => part.trim());
         const parsedStart = parseISODate(rawStart);
         const parsedEnd = parseISODate(rawEnd);
         if (parsedStart || parsedEnd) {
@@ -106,7 +108,8 @@ export async function executeReconciliation(options) {
     let accountSnapshotDirty = false;
     const statementTargetMilli = resolveStatementBalanceMilli(analysis.balance_info, params.statement_balance);
     let clearedDeltaMilli = addMilli(initialAccount.cleared_balance ?? 0, -statementTargetMilli);
-    const balanceToleranceMilli = Math.max(0, params.amount_tolerance_cents ?? DEFAULT_TOLERANCE_CENTS) * CENTS_TO_MILLI;
+    const balanceToleranceMilli = Math.max(0, params.amount_tolerance_cents ?? DEFAULT_TOLERANCE_CENTS) *
+        CENTS_TO_MILLI;
     let balanceAligned = false;
     const applyClearedDelta = (delta) => {
         if (delta === 0)
@@ -123,7 +126,7 @@ export async function executeReconciliation(options) {
                 const deltaDisplay = toMoneyValue(clearedDeltaMilli, currencyCode).value_display;
                 const toleranceDisplay = toMoneyValue(balanceToleranceMilli, currencyCode).value_display;
                 actions_taken.push({
-                    type: 'balance_checkpoint',
+                    type: "balance_checkpoint",
                     transaction: null,
                     reason: `Cleared delta ${deltaDisplay} within ±${toleranceDisplay} after ${trigger} - halting newest-to-oldest pass`,
                 });
@@ -132,7 +135,7 @@ export async function executeReconciliation(options) {
         }
         return false;
     };
-    recordAlignmentIfNeeded('initial balance check', { log: false });
+    recordAlignmentIfNeeded("initial balance check", { log: false });
     const orderedUnmatchedBank = params.auto_create_transactions
         ? sortByDateDescending(analysis.unmatched_bank)
         : [];
@@ -151,7 +154,7 @@ export async function executeReconciliation(options) {
                 date: bankTxn.date,
                 payee_name: bankTxn.payee ?? undefined,
                 memo: truncateMemo(bankTxn.memo),
-                cleared: 'cleared',
+                cleared: "cleared",
                 approved: true,
             };
             const correlationKey = generateCorrelationKey(toCorrelationPayload(saveTransaction));
@@ -166,9 +169,9 @@ export async function executeReconciliation(options) {
             const { entry, createdTxn, chunkIndex, prefix } = args;
             summary.transactions_created += 1;
             const action = {
-                type: 'create_transaction',
+                type: "create_transaction",
                 transaction: createdTxn,
-                reason: `${prefix ?? 'Created missing transaction'}: ${entry.bankTransaction.payee ?? 'Unknown'} (${formatDisplay(entry.bankTransaction.amount, currencyCode)})`,
+                reason: `${prefix ?? "Created missing transaction"}: ${entry.bankTransaction.payee ?? "Unknown"} (${formatDisplay(entry.bankTransaction.amount, currencyCode)})`,
                 correlation_key: entry.correlationKey,
             };
             if (chunkIndex !== undefined) {
@@ -193,8 +196,8 @@ export async function executeReconciliation(options) {
                         entry,
                         createdTxn: createdTransaction,
                         prefix: options.fallbackError
-                            ? 'Created missing transaction after bulk fallback'
-                            : 'Created missing transaction',
+                            ? "Created missing transaction after bulk fallback"
+                            : "Created missing transaction",
                     };
                     if (options.chunkIndex !== undefined) {
                         recordArgs.chunkIndex = options.chunkIndex;
@@ -205,8 +208,8 @@ export async function executeReconciliation(options) {
                     completedOperations += 1;
                     await reportProgress(`Created ${completedOperations} of ${totalOperations} transactions`);
                     const trigger = options.chunkIndex
-                        ? `creating ${entry.bankTransaction.payee ?? 'missing transaction'} (chunk ${options.chunkIndex})`
-                        : `creating ${entry.bankTransaction.payee ?? 'missing transaction'}`;
+                        ? `creating ${entry.bankTransaction.payee ?? "missing transaction"} (chunk ${options.chunkIndex})`
+                        : `creating ${entry.bankTransaction.payee ?? "missing transaction"}`;
                     recordAlignmentIfNeeded(trigger);
                 }
                 catch (error) {
@@ -214,14 +217,16 @@ export async function executeReconciliation(options) {
                     if (bulkOperationDetails) {
                         bulkOperationDetails.transaction_failures += 1;
                     }
-                    const failureReason = ynabError.message || 'Unknown error occurred';
-                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
+                    const failureReason = ynabError.message || "Unknown error occurred";
+                    const statusSuffix = ynabError.status
+                        ? ` (HTTP ${ynabError.status})`
+                        : "";
                     const failureAction = {
-                        type: 'create_transaction_failed',
+                        type: "create_transaction_failed",
                         transaction: entry.saveTransaction,
                         reason: options.fallbackError
-                            ? `Bulk fallback failed for ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason}${statusSuffix})`
-                            : `Failed to create transaction ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason}${statusSuffix})`,
+                            ? `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) {
@@ -233,12 +238,17 @@ export async function executeReconciliation(options) {
                     }
                 }
             }
-            if (bulkOperationDetails && options.fallbackError && sequentialAttempts > 0) {
+            if (bulkOperationDetails &&
+                options.fallbackError &&
+                sequentialAttempts > 0) {
                 bulkOperationDetails.sequential_attempts =
                     (bulkOperationDetails.sequential_attempts ?? 0) + sequentialAttempts;
             }
         };
         const processBulkChunk = async (chunk, chunkIndex) => {
+            if (!bulkOperationDetails) {
+                throw new Error("Bulk operation details not initialized");
+            }
             const bulkDetails = bulkOperationDetails;
             const payload = chunk.map((entry) => entry.saveTransaction);
             const response = await ynabAPI.transactions.createTransactions(budgetId, {
@@ -258,7 +268,7 @@ export async function executeReconciliation(options) {
                 const entry = chunk[result.request_index];
                 if (!entry)
                     continue;
-                if (result.status === 'created') {
+                if (result.status === "created") {
                     const createdTransaction = result.transaction_id
                         ? (transactionMap.get(result.transaction_id) ?? null)
                         : null;
@@ -266,21 +276,21 @@ export async function executeReconciliation(options) {
                         entry,
                         createdTxn: createdTransaction,
                         chunkIndex,
-                        prefix: 'Created missing transaction via bulk',
+                        prefix: "Created missing transaction via bulk",
                     });
                     accountSnapshotDirty = true;
                     applyClearedDelta(entry.amountMilli);
-                    recordAlignmentIfNeeded(`creating ${entry.bankTransaction.payee ?? 'missing transaction'} via bulk chunk ${chunkIndex}`);
+                    recordAlignmentIfNeeded(`creating ${entry.bankTransaction.payee ?? "missing transaction"} via bulk chunk ${chunkIndex}`);
                 }
-                else if (result.status === 'duplicate') {
+                else if (result.status === "duplicate") {
                     bulkDetails.duplicates_detected += 1;
                     actions_taken.push({
-                        type: 'create_transaction_duplicate',
+                        type: "create_transaction_duplicate",
                         transaction: {
                             transaction_id: result.transaction_id ?? null,
                             import_id: entry.saveTransaction.import_id,
                         },
-                        reason: `Duplicate import detected for ${entry.bankTransaction.payee ?? 'Unknown'} (import_id ${entry.saveTransaction.import_id})`,
+                        reason: `Duplicate import detected for ${entry.bankTransaction.payee ?? "Unknown"} (import_id ${entry.saveTransaction.import_id})`,
                         bulk_chunk_index: chunkIndex,
                         correlation_key: result.correlation_key,
                         duplicate: true,
@@ -289,9 +299,10 @@ export async function executeReconciliation(options) {
                 else {
                     bulkDetails.transaction_failures += 1;
                     actions_taken.push({
-                        type: 'create_transaction_failed',
+                        type: "create_transaction_failed",
                         transaction: entry.saveTransaction,
-                        reason: result.error ?? `Bulk create failed for ${entry.bankTransaction.payee ?? 'Unknown'}`,
+                        reason: result.error ??
+                            `Bulk create failed for ${entry.bankTransaction.payee ?? "Unknown"}`,
                         bulk_chunk_index: chunkIndex,
                         correlation_key: result.correlation_key,
                     });
@@ -305,13 +316,13 @@ export async function executeReconciliation(options) {
                 const entry = buildPreparedEntry(bankTxn);
                 summary.transactions_created += 1;
                 actions_taken.push({
-                    type: 'create_transaction',
+                    type: "create_transaction",
                     transaction: entry.saveTransaction,
-                    reason: `Would create missing transaction: ${bankTxn.payee ?? 'Unknown'} (${formatDisplay(bankTxn.amount, currencyCode)})`,
+                    reason: `Would create missing transaction: ${bankTxn.payee ?? "Unknown"} (${formatDisplay(bankTxn.amount, currencyCode)})`,
                     correlation_key: entry.correlationKey,
                 });
                 applyClearedDelta(entry.amountMilli);
-                recordAlignmentIfNeeded(`creating ${bankTxn.payee ?? 'missing transaction'}`);
+                recordAlignmentIfNeeded(`creating ${bankTxn.payee ?? "missing transaction"}`);
             }
         }
         else if (orderedUnmatchedBank.length >= 2) {
@@ -359,7 +370,7 @@ export async function executeReconciliation(options) {
                     }
                     catch (error) {
                         const ynabError = normalizeYnabError(error);
-                        const failureReason = ynabError.message || 'unknown error';
+                        const failureReason = ynabError.message || "unknown error";
                         bulkOperationDetails.bulk_chunk_failures += 1;
                         if (shouldPropagateYnabError(ynabError)) {
                             bulkOperationDetails.transaction_failures += chunk.length;
@@ -367,12 +378,15 @@ export async function executeReconciliation(options) {
                         }
                         bulkOperationDetails.sequential_fallbacks += 1;
                         actions_taken.push({
-                            type: 'bulk_create_fallback',
+                            type: "bulk_create_fallback",
                             transaction: null,
-                            reason: `Bulk chunk #${chunkIndex} failed (${failureReason}${ynabError.status ? ` (HTTP ${ynabError.status})` : ''}) - 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: ynabError });
+                        await processSequentialEntries(chunk, {
+                            chunkIndex,
+                            fallbackError: ynabError,
+                        });
                     }
                 }
             }
@@ -402,24 +416,26 @@ export async function executeReconciliation(options) {
                 updatePayload.date = match.bankTransaction.date;
             }
             if (flags.needsClearedUpdate) {
-                updatePayload.cleared = 'cleared';
+                updatePayload.cleared = "cleared";
             }
             if (params.dry_run) {
                 summary.transactions_updated += 1;
                 if (flags.needsDateUpdate)
                     summary.dates_adjusted += 1;
                 actions_taken.push({
-                    type: 'update_transaction',
+                    type: "update_transaction",
                     transaction: {
                         transaction_id: match.ynabTransaction.id,
-                        new_date: flags.needsDateUpdate ? match.bankTransaction.date : undefined,
-                        cleared: flags.needsClearedUpdate ? 'cleared' : undefined,
+                        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.ynabTransaction.amount);
-                    if (recordAlignmentIfNeeded(`clearing ${match.ynabTransaction.id ?? 'transaction'} (dry run)`)) {
+                    if (recordAlignmentIfNeeded(`clearing ${match.ynabTransaction.id ?? "transaction"} (dry run)`)) {
                         break;
                     }
                 }
@@ -440,6 +456,8 @@ export async function executeReconciliation(options) {
             const updateChunks = chunkArray(transactionsToUpdate, MAX_BULK_UPDATE_CHUNK);
             for (let chunkIdx = 0; chunkIdx < updateChunks.length; chunkIdx++) {
                 const chunk = updateChunks[chunkIdx];
+                if (!chunk)
+                    continue;
                 try {
                     const response = await ynabAPI.transactions.updateTransactions(budgetId, {
                         transactions: chunk,
@@ -452,9 +470,9 @@ export async function executeReconciliation(options) {
                             ? computeUpdateFlags(match, params)
                             : { needsClearedUpdate: false, needsDateUpdate: false };
                         actions_taken.push({
-                            type: 'update_transaction',
+                            type: "update_transaction",
                             transaction: updatedTransaction,
-                            reason: `Updated transaction: ${match ? updateReason(match, flags, currencyCode) : 'cleared'}`,
+                            reason: `Updated transaction: ${match ? updateReason(match, flags, currencyCode) : "cleared"}`,
                         });
                     }
                     accountSnapshotDirty = true;
@@ -463,10 +481,12 @@ export async function executeReconciliation(options) {
                 }
                 catch (error) {
                     const ynabError = normalizeYnabError(error);
-                    const failureReason = ynabError.message || 'Unknown error occurred';
-                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
+                    const failureReason = ynabError.message || "Unknown error occurred";
+                    const statusSuffix = ynabError.status
+                        ? ` (HTTP ${ynabError.status})`
+                        : "";
                     actions_taken.push({
-                        type: 'batch_update_failed',
+                        type: "batch_update_failed",
                         transaction: null,
                         reason: `Failed to update chunk ${chunkIdx + 1}/${updateChunks.length} (${chunk.length} transaction(s)): ${failureReason}${statusSuffix}`,
                     });
@@ -482,7 +502,7 @@ export async function executeReconciliation(options) {
     }
     const shouldRunSanityPass = params.auto_unclear_missing && !balanceAligned;
     actions_taken.push({
-        type: 'diagnostic_step3_entry',
+        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}`,
     });
@@ -492,26 +512,28 @@ export async function executeReconciliation(options) {
             date: t.date,
             cleared: t.cleared,
             amount: formatDisplay(t.amount, currencyCode),
-            payee: t.payee ?? 'Unknown',
+            payee: t.payee ?? "Unknown",
         }));
         actions_taken.push({
-            type: 'diagnostic_unmatched_ynab',
-            transaction: { unmatched_transactions: unmatchedDetails },
+            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) {
-            if (ynabTxn.cleared !== 'cleared')
+            if (ynabTxn.cleared !== "cleared")
                 continue;
             if (balanceAligned)
                 break;
             if (params.dry_run) {
                 summary.transactions_updated += 1;
                 actions_taken.push({
-                    type: 'update_transaction',
-                    transaction: { transaction_id: ynabTxn.id, cleared: 'uncleared' },
+                    type: "update_transaction",
+                    transaction: { transaction_id: ynabTxn.id, cleared: "uncleared" },
                     reason: `Would mark transaction ${ynabTxn.id} as uncleared - not present on statement`,
                 });
                 applyClearedDelta(-ynabTxn.amount);
@@ -522,7 +544,7 @@ export async function executeReconciliation(options) {
             else {
                 transactionsToUnclear.push({
                     id: ynabTxn.id,
-                    cleared: 'uncleared',
+                    cleared: "uncleared",
                 });
                 applyClearedDelta(-ynabTxn.amount);
                 if (recordAlignmentIfNeeded(`unclearing ${ynabTxn.id}`)) {
@@ -534,6 +556,8 @@ export async function executeReconciliation(options) {
             const unclearChunks = chunkArray(transactionsToUnclear, MAX_BULK_UPDATE_CHUNK);
             for (let chunkIdx = 0; chunkIdx < unclearChunks.length; chunkIdx++) {
                 const chunk = unclearChunks[chunkIdx];
+                if (!chunk)
+                    continue;
                 try {
                     const response = await ynabAPI.transactions.updateTransactions(budgetId, {
                         transactions: chunk,
@@ -542,7 +566,7 @@ export async function executeReconciliation(options) {
                     summary.transactions_updated += updatedTransactions.length;
                     for (const updatedTransaction of updatedTransactions) {
                         actions_taken.push({
-                            type: 'update_transaction',
+                            type: "update_transaction",
                             transaction: updatedTransaction,
                             reason: `Marked transaction ${updatedTransaction.id} as uncleared - not found on statement`,
                         });
@@ -553,10 +577,12 @@ export async function executeReconciliation(options) {
                 }
                 catch (error) {
                     const ynabError = normalizeYnabError(error);
-                    const failureReason = ynabError.message || 'Unknown error occurred';
-                    const statusSuffix = ynabError.status ? ` (HTTP ${ynabError.status})` : '';
+                    const failureReason = ynabError.message || "Unknown error occurred";
+                    const statusSuffix = ynabError.status
+                        ? ` (HTTP ${ynabError.status})`
+                        : "";
                     actions_taken.push({
-                        type: 'batch_unclear_failed',
+                        type: "batch_unclear_failed",
                         transaction: null,
                         reason: `Failed to unclear chunk ${chunkIdx + 1}/${unclearChunks.length} (${chunk.length} transaction(s)): ${failureReason}${statusSuffix}`,
                     });
@@ -575,17 +601,19 @@ export async function executeReconciliation(options) {
         for (const match of orderedAutoMatches) {
             if (!match.ynabTransaction)
                 continue;
-            if (match.ynabTransaction.cleared === 'reconciled')
+            if (match.ynabTransaction.cleared === "reconciled")
                 continue;
             transactionsToReconcile.push({
                 id: match.ynabTransaction.id,
-                cleared: 'reconciled',
+                cleared: "reconciled",
             });
         }
         if (transactionsToReconcile.length > 0) {
             const reconcileChunks = chunkArray(transactionsToReconcile, MAX_BULK_UPDATE_CHUNK);
             for (let chunkIdx = 0; chunkIdx < reconcileChunks.length; chunkIdx++) {
                 const chunk = reconcileChunks[chunkIdx];
+                if (!chunk)
+                    continue;
                 try {
                     const response = await ynabAPI.transactions.updateTransactions(budgetId, {
                         transactions: chunk,
@@ -595,19 +623,21 @@ export async function executeReconciliation(options) {
                     for (const reconciledTransaction of reconciledTransactions) {
                         const match = orderedAutoMatches.find((m) => m.ynabTransaction?.id === reconciledTransaction.id);
                         actions_taken.push({
-                            type: 'update_transaction',
+                            type: "update_transaction",
                             transaction: reconciledTransaction,
-                            reason: `Marked as reconciled: ${match?.bankTransaction.payee ?? 'transaction'} (${formatDisplay(reconciledTransaction.amount, currencyCode)})`,
+                            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})` : '';
+                    const failureReason = ynabError.message || "Unknown error occurred";
+                    const statusSuffix = ynabError.status
+                        ? ` (HTTP ${ynabError.status})`
+                        : "";
                     actions_taken.push({
-                        type: 'batch_reconcile_failed',
+                        type: "batch_reconcile_failed",
                         transaction: null,
                         reason: `Failed to reconcile chunk ${chunkIdx + 1}/${reconcileChunks.length} (${chunk.length} transaction(s)): ${failureReason}${statusSuffix}`,
                     });
@@ -620,7 +650,7 @@ export async function executeReconciliation(options) {
                 }
             }
             actions_taken.push({
-                type: 'reconciliation_complete',
+                type: "reconciliation_complete",
                 transaction: null,
                 reason: `Marked ${transactionsToReconcile.length} matched transaction(s) as reconciled - balance aligned within tolerance`,
             });
@@ -640,7 +670,9 @@ export async function executeReconciliation(options) {
     if (!params.dry_run && accountSnapshotDirty) {
         afterAccount = await refreshAccountSnapshot(ynabAPI, budgetId, accountId);
     }
-    const balanceChangeMilli = params.dry_run || !accountSnapshotDirty ? 0 : afterAccount.balance - initialAccount.balance;
+    const balanceChangeMilli = params.dry_run || !accountSnapshotDirty
+        ? 0
+        : afterAccount.balance - initialAccount.balance;
     const recommendations = buildRecommendations({
         summary,
         params,
@@ -661,7 +693,8 @@ export async function executeReconciliation(options) {
         result.balance_reconciliation = balance_reconciliation;
     }
     if (bulkOperationDetails) {
-        bulkOperationDetails.failed_transactions = bulkOperationDetails.transaction_failures;
+        bulkOperationDetails.failed_transactions =
+            bulkOperationDetails.transaction_failures;
         result.bulk_operation_details = bulkOperationDetails;
     }
     return result;
@@ -669,9 +702,9 @@ export async function executeReconciliation(options) {
 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))
+        if (typeof value === "number" && Number.isFinite(value))
             return value;
-        if (typeof value === 'string') {
+        if (typeof value === "string") {
             const numeric = Number(value);
             if (Number.isFinite(numeric))
                 return numeric;
@@ -682,10 +715,12 @@ export function normalizeYnabError(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 detail = typeof detailSource === "string" && detailSource.trim().length > 0
+            ? detailSource
+            : undefined;
         const result = {
             name: error.name,
-            message: error.message || 'Unknown error occurred',
+            message: error.message || "Unknown error occurred",
         };
         if (status !== undefined)
             result.status = status;
@@ -693,18 +728,21 @@ export function normalizeYnabError(error) {
             result.detail = detail;
         return result;
     }
-    if (error && typeof error === 'object') {
+    if (error && typeof error === "object") {
         const errObj = error.error ?? error;
-        const status = parseStatus(errObj.id ?? errObj.status);
+        const status = parseStatus(errObj.id ??
+            errObj.status);
         const detailCandidate = errObj.detail ??
             errObj.message ??
             errObj.name;
-        const detail = typeof detailCandidate === 'string' && detailCandidate.trim().length > 0
+        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'
+            (typeof errObj === "string" && errObj.trim().length > 0
+                ? errObj
+                : "Unknown error occurred");
+        const name = typeof errObj.name === "string"
             ? errObj.name
             : undefined;
         const result = { message };
@@ -716,27 +754,27 @@ export function normalizeYnabError(error) {
             result.detail = detail;
         return result;
     }
-    if (typeof error === 'string') {
+    if (typeof error === "string") {
         return { message: error };
     }
-    return { message: 'Unknown error occurred' };
+    return { message: "Unknown error occurred" };
 }
 export function shouldPropagateYnabError(error) {
-    return error.status !== undefined && FATAL_YNAB_STATUS_CODES.has(error.status);
+    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;
+    const message = error.message || "YNAB API error";
+    const isKnownCode = error.status === YNABErrorCode.BAD_REQUEST ||
+        error.status === YNABErrorCode.UNAUTHORIZED ||
+        error.status === YNABErrorCode.FORBIDDEN ||
+        error.status === YNABErrorCode.NOT_FOUND ||
+        error.status === YNABErrorCode.TOO_MANY_REQUESTS ||
+        error.status === YNABErrorCode.INTERNAL_SERVER_ERROR;
     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 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;
@@ -755,26 +793,26 @@ function computeUpdateFlags(match, params) {
     if (!ynabTxn) {
         return { needsClearedUpdate: false, needsDateUpdate: false };
     }
-    const needsClearedUpdate = Boolean(params.auto_update_cleared_status && ynabTxn.cleared !== 'cleared');
+    const needsClearedUpdate = Boolean(params.auto_update_cleared_status && ynabTxn.cleared !== "cleared");
     const needsDateUpdate = Boolean(params.auto_adjust_dates && ynabTxn.date !== bankTxn.date);
     return { needsClearedUpdate, needsDateUpdate };
 }
 function updateReason(match, flags, _currency) {
     const parts = [];
     if (flags.needsClearedUpdate) {
-        parts.push('marked as cleared');
+        parts.push("marked as cleared");
     }
     if (flags.needsDateUpdate) {
         parts.push(`date adjusted to ${match.bankTransaction.date}`);
     }
-    return parts.join(', ');
+    return parts.join(", ");
 }
 async function buildBalanceReconciliation(args) {
     const { ynabAPI, budgetId, accountId, statementDate, statementBalance } = args;
     const ynabMilli = await clearedBalanceAsOf(ynabAPI, budgetId, accountId, statementDate);
     const bankMilli = toMilli(statementBalance);
     const discrepancy = bankMilli - ynabMilli;
-    const status = discrepancy === 0 ? 'PERFECTLY_RECONCILED' : 'DISCREPANCY_FOUND';
+    const status = discrepancy === 0 ? "PERFECTLY_RECONCILED" : "DISCREPANCY_FOUND";
     const precision_calculations = {
         bank_statement_balance_milliunits: bankMilli,
         ynab_calculated_balance_milliunits: ynabMilli,
@@ -800,7 +838,7 @@ async function buildBalanceReconciliation(args) {
 async function clearedBalanceAsOf(api, budgetId, accountId, dateISO) {
     const response = await api.transactions.getTransactionsByAccount(budgetId, accountId);
     const asOf = new Date(dateISO);
-    const cleared = response.data.transactions.filter((txn) => txn.cleared === 'cleared' && new Date(txn.date) <= asOf);
+    const cleared = response.data.transactions.filter((txn) => txn.cleared === "cleared" && new Date(txn.date) <= asOf);
     const sum = cleared.reduce((acc, txn) => addMilli(acc, txn.amount ?? 0), 0);
     return sum;
 }
@@ -821,13 +859,13 @@ function buildLikelyCauses(discrepancyMilli) {
     const abs = Math.abs(discrepancyMilli);
     if (abs % 1000 === 0 || abs % 500 === 0) {
         causes.push({
-            cause_type: 'bank_fee',
-            description: 'Round amount suggests a bank fee or interest adjustment.',
+            cause_type: "bank_fee",
+            description: "Round amount suggests a bank fee or interest adjustment.",
             confidence: 0.8,
             amount_milliunits: discrepancyMilli,
             suggested_resolution: discrepancyMilli < 0
-                ? 'Create bank fee transaction and mark cleared'
-                : 'Record interest income',
+                ? "Create bank fee transaction and mark cleared"
+                : "Record interest income",
             evidence: [],
         });
     }
@@ -835,7 +873,7 @@ function buildLikelyCauses(discrepancyMilli) {
         ? {
             confidence_level: Math.max(...causes.map((cause) => cause.confidence)),
             likely_causes: causes,
-            risk_assessment: 'LOW',
+            risk_assessment: "LOW",
         }
         : undefined;
 }
@@ -849,13 +887,13 @@ function buildRecommendations(args) {
         recommendations.push(`Consider enabling auto_create_transactions to automatically create ${analysis.summary.unmatched_bank} missing transaction(s)`);
     }
     if (!params.auto_adjust_dates && analysis.auto_matches.length > 0) {
-        recommendations.push('Consider enabling auto_adjust_dates to align YNAB dates with bank statement dates');
+        recommendations.push("Consider enabling auto_adjust_dates to align YNAB dates with bank statement dates");
     }
     if (analysis.summary.unmatched_ynab > 0) {
         recommendations.push(`${analysis.summary.unmatched_ynab} transaction(s) exist in YNAB but not on the bank statement — review for duplicates or pending items`);
     }
     if (params.dry_run) {
-        recommendations.push('Dry run only — re-run with dry_run=false to apply these changes');
+        recommendations.push("Dry run only — re-run with dry_run=false to apply these changes");
     }
     if (Math.abs(balanceChangeMilli) > MONEY_EPSILON_MILLI) {
         recommendations.push(`Account balance changed by ${toMoneyValue(balanceChangeMilli, currencyCode).value_display} during reconciliation`);
@@ -863,7 +901,7 @@ function buildRecommendations(args) {
     return recommendations;
 }
 function resolveStatementBalanceMilli(balanceInfo, provided) {
-    if (typeof provided === 'number' && Number.isFinite(provided)) {
+    if (typeof provided === "number" && Number.isFinite(provided)) {
         return toMilli(provided);
     }
     return (extractMoneyValue(balanceInfo?.target_statement) ??
@@ -871,13 +909,14 @@ function resolveStatementBalanceMilli(balanceInfo, provided) {
         0);
 }
 function extractMoneyValue(value) {
-    if (typeof value === 'number' && Number.isFinite(value)) {
+    if (typeof value === "number" && Number.isFinite(value)) {
         return toMilli(value);
     }
     if (value &&
-        typeof value === 'object' &&
-        'value_milliunits' in value &&
-        typeof value.value_milliunits === 'number') {
+        typeof value === "object" &&
+        "value_milliunits" in value &&
+        typeof value.value_milliunits ===
+            "number") {
         return value.value_milliunits;
     }
     return undefined;