@dizzlkheinz/ynab-mcpb 0.26.2 → 0.26.4

package/dist/tools/reconciliation/executor.js

@@ -16,16 +16,9 @@ function parseISODate(dateStr) {
     return Number.isNaN(d.getTime()) ? undefined : d;
 }
 function resolveStatementWindow(params, analysisDateRange) {
-    const start = parseISODate(params.statement_start_date);
-    const end = parseISODate(params.statement_end_date ?? params.statement_date) ??
-        undefined;
-    if (start || end) {
-        const window = {};
-        if (start)
-            window.start = start;
-        if (end)
-            window.end = end;
-        return window;
+    const end = parseISODate(params.statement_end_date);
+    if (end) {
+        return { end };
     }
     if (analysisDateRange?.includes(" to ")) {
         const [rawStart, rawEnd] = analysisDateRange
@@ -637,12 +630,12 @@ export async function executeReconciliation(options) {
         }
     }
     let balance_reconciliation;
-    if (params.statement_balance !== undefined && params.statement_date) {
+    if (params.statement_balance !== undefined && params.statement_end_date) {
         balance_reconciliation = await buildBalanceReconciliation({
             ynabAPI,
             budgetId,
             accountId,
-            statementDate: params.statement_date,
+            statementDate: params.statement_end_date,
             statementBalanceMilli: statementTargetMilli,
             analysis,
         });

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

@@ -24,27 +24,24 @@ export declare const ReconcileAccountSchema: z.ZodObject<{
         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>;
-    statement_date: z.ZodOptional<z.ZodString>;
-    expected_bank_balance: z.ZodOptional<z.ZodNumber>;
-    as_of_timezone: z.ZodOptional<z.ZodString>;
     date_tolerance_days: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    auto_match_threshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    suggestion_threshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    match_strictness: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        loose: "loose";
+        normal: "normal";
+        strict: "strict";
+    }>>>;
     auto_create_transactions: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     auto_update_cleared_status: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     auto_unclear_missing: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     auto_adjust_dates: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    invert_bank_amounts: z.ZodOptional<z.ZodBoolean>;
     dry_run: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    include_structured_data: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    structured_content: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
-        full: "full";
-        unmatched_only: "unmatched_only";
+    sign_convention: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        invert: "invert";
+        as_is: "as_is";
     }>>>;
     max_suggestions_in_output: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    force_full_refresh: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type ReconcileAccountRequest = z.infer<typeof ReconcileAccountSchema>;
 export declare function handleReconcileAccount(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ReconcileAccountRequest, sendProgress?: ProgressCallback): Promise<CallToolResult>;

package/dist/tools/reconciliation/index.js

@@ -18,27 +18,6 @@ import { normalizeYNABTransactions } from "./ynabAdapter.js";
 export { analyzeReconciliation } from "./analyzer.js";
 export { findBestMatch, findMatches } from "./matcher.js";
 export { fuzzyMatch, normalizedMatch, normalizePayee, payeeSimilarity, } from "./payeeNormalizer.js";
-function getAuditDataSource(transactionsResult, forceFullRefresh) {
-    if (forceFullRefresh) {
-        return "full_api_fetch_no_delta";
-    }
-    if (transactionsResult.usedDelta) {
-        return "delta_fetch_with_merge";
-    }
-    if (transactionsResult.wasCached) {
-        return "delta_fetch_cache_hit";
-    }
-    return "delta_fetch_full_refresh";
-}
-function getDataFreshness(transactionsResult, forceFullRefresh) {
-    if (forceFullRefresh) {
-        return "guaranteed_fresh";
-    }
-    if (transactionsResult.wasCached) {
-        return "cache_validated_via_server_knowledge";
-    }
-    return "fresh_via_delta_fetch";
-}
 export const ReconcileAccountSchema = z
     .object({
     budget_id: z.string().min(1, "Budget ID is required"),
@@ -61,27 +40,22 @@ export const ReconcileAccountSchema = z
     statement_balance: z.number({
         message: "Statement balance is required and must be a number",
     }),
-    statement_start_date: z.string().optional(),
     statement_end_date: z.string().optional(),
-    statement_date: z.string().optional(),
-    expected_bank_balance: z.number().optional(),
-    as_of_timezone: z.string().optional(),
     date_tolerance_days: z.number().min(0).max(7).optional().default(7),
-    auto_match_threshold: z.number().min(0).max(100).optional().default(85),
-    suggestion_threshold: z.number().min(0).max(100).optional().default(60),
+    match_strictness: z
+        .enum(["loose", "normal", "strict"])
+        .optional()
+        .default("normal"),
     auto_create_transactions: z.boolean().optional().default(false),
     auto_update_cleared_status: z.boolean().optional().default(false),
     auto_unclear_missing: z.boolean().optional().default(true),
     auto_adjust_dates: z.boolean().optional().default(false),
-    invert_bank_amounts: z.boolean().optional(),
     dry_run: z.boolean().optional().default(true),
-    include_structured_data: z.boolean().optional().default(false),
-    structured_content: z
-        .enum(["full", "unmatched_only"])
+    sign_convention: z
+        .enum(["auto", "invert", "as_is"])
         .optional()
-        .default("full"),
+        .default("auto"),
     max_suggestions_in_output: z.number().int().min(1).optional().default(20),
-    force_full_refresh: z.boolean().optional().default(true),
 })
     .refine((data) => data.csv_file_path || data.csv_data, {
     message: "csv_data or csv_file_path is required. " +
@@ -92,23 +66,27 @@ export const ReconcileAccountSchema = z
 });
 export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, maybeParams, sendProgress, errorHandler) {
     const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
-    const forceFullRefresh = params.force_full_refresh ?? true;
     return await withToolErrorHandling(async () => {
+        const STRICTNESS_THRESHOLDS = {
+            loose: { autoMatch: 70, suggested: 55 },
+            normal: { autoMatch: 85, suggested: 60 },
+            strict: { autoMatch: 93, suggested: 75 },
+        };
+        const strictness = params.match_strictness ?? "normal";
+        const { autoMatch: autoMatchThreshold, suggested: suggestionThreshold } = STRICTNESS_THRESHOLDS[strictness];
         const config = {
             weights: {
                 date: 0.15,
                 payee: 0.35,
             },
             dateToleranceDays: params.date_tolerance_days ?? 7,
-            autoMatchThreshold: params.auto_match_threshold ?? 85,
-            suggestedMatchThreshold: params.suggestion_threshold ?? 60,
+            autoMatchThreshold,
+            suggestedMatchThreshold: suggestionThreshold,
             minimumCandidateScore: 40,
             exactDateBonus: 5,
             exactPayeeBonus: 10,
         };
-        const accountResult = forceFullRefresh
-            ? await deltaFetcher.fetchAccountsFull(params.budget_id)
-            : await deltaFetcher.fetchAccounts(params.budget_id);
+        const accountResult = await deltaFetcher.fetchAccountsFull(params.budget_id);
         const accountData = accountResult.data.find((account) => account.id === params.account_id);
         if (!accountData) {
             throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
@@ -124,9 +102,7 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             accountType === "medicalDebt" ||
             accountType === "otherDebt" ||
             accountType === "otherLiability";
-        const shouldInvertBankAmounts = params.invert_bank_amounts !== undefined
-            ? params.invert_bank_amounts
-            : accountIsLiability;
+        const shouldInvertBankAmounts = accountIsLiability;
         const adjustedStatementBalance = accountIsLiability
             ? -Math.abs(params.statement_balance)
             : params.statement_balance;
@@ -202,12 +178,8 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
                 : "Unknown error while parsing CSV";
             throw new Error(`Failed to parse CSV data: ${message}`);
         }
-        const statementWindowStart = normalizeStatementDate(params.statement_start_date);
-        const statementWindowEnd = normalizeStatementDate(params.statement_end_date ?? params.statement_date);
+        const statementWindowEnd = normalizeStatementDate(params.statement_end_date);
         const statementWindowBounds = {
-            ...(statementWindowStart !== undefined && {
-                startDate: statementWindowStart,
-            }),
             ...(statementWindowEnd !== undefined && {
                 endDate: statementWindowEnd,
             }),
@@ -222,13 +194,15 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
         if (clampedCsv.windowApplied && rawCsvResult.transactions.length === 0) {
             throw new Error(`No CSV transactions remain after applying statement window ${formatStatementWindow(clampedCsv.windowApplied)}.`);
         }
+        const effectiveStatementEndDate = statementWindowEnd ??
+            inferLatestTransactionDate(rawCsvResult.transactions);
+        if (statementWindowEnd === undefined &&
+            effectiveStatementEndDate !== undefined) {
+            narrativeNotes.push(`Auto-detected statement_end_date=${effectiveStatementEndDate} from the latest CSV transaction for balance verification.`);
+        }
         let sinceDate;
         let dateWindowSource;
-        if (params.statement_start_date) {
-            sinceDate = new Date(params.statement_start_date);
-            dateWindowSource = "statement_start_date";
-        }
-        else if (rawCsvResult.transactions.length > 0) {
+        if (rawCsvResult.transactions.length > 0) {
             sinceDate = inferSinceDateFromTransactions(rawCsvResult.transactions);
             dateWindowSource = "csv_min_date_with_buffer";
         }
@@ -238,23 +212,31 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             narrativeNotes.push("CSV contained no parsable transactions for date detection; fetched the last 90 days from YNAB.");
         }
         const sinceDateString = sinceDate.toISOString().split("T")[0];
-        const transactionsResult = forceFullRefresh
-            ? await deltaFetcher.fetchTransactionsByAccountFull(params.budget_id, params.account_id, sinceDateString)
-            : await deltaFetcher.fetchTransactionsByAccount(params.budget_id, params.account_id, sinceDateString);
+        const transactionsResult = await deltaFetcher.fetchTransactionsByAccountFull(params.budget_id, params.account_id, sinceDateString);
         const ynabTransactions = transactionsResult.data;
         const normalizedYNAB = normalizeYNABTransactions(ynabTransactions);
-        let finalInvertAmounts = shouldInvertBankAmounts;
-        if (params.invert_bank_amounts === undefined &&
-            rawCsvResult.transactions.length > 0 &&
-            normalizedYNAB.length > 0) {
-            const needsInversion = detectSignInversion(rawCsvResult.transactions, normalizedYNAB);
-            if (needsInversion !== null) {
-                if (needsInversion !== finalInvertAmounts) {
-                    narrativeNotes.push(needsInversion
-                        ? "Detected bank CSV amounts opposite YNAB; inverting bank amounts for matching."
-                        : "Detected bank CSV amounts already align with YNAB; using CSV amounts as-is.");
+        const signConvention = params.sign_convention ?? "auto";
+        let finalInvertAmounts;
+        if (signConvention === "invert") {
+            finalInvertAmounts = true;
+            narrativeNotes.push("Using explicit sign_convention=invert; bank amounts will be negated.");
+        }
+        else if (signConvention === "as_is") {
+            finalInvertAmounts = false;
+            narrativeNotes.push("Using explicit sign_convention=as_is; bank amounts used as-is.");
+        }
+        else {
+            finalInvertAmounts = shouldInvertBankAmounts;
+            if (rawCsvResult.transactions.length > 0 && normalizedYNAB.length > 0) {
+                const needsInversion = detectSignInversion(rawCsvResult.transactions, normalizedYNAB);
+                if (needsInversion !== null) {
+                    if (needsInversion !== finalInvertAmounts) {
+                        narrativeNotes.push(needsInversion
+                            ? "Detected bank CSV amounts opposite YNAB; inverting bank amounts for matching."
+                            : "Detected bank CSV amounts already align with YNAB; using CSV amounts as-is.");
+                    }
+                    finalInvertAmounts = needsInversion;
                 }
-                finalInvertAmounts = needsInversion;
             }
         }
         const parseResult = finalInvertAmounts
@@ -267,8 +249,8 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             }
             : rawCsvResult;
         const auditMetadata = {
-            data_freshness: getDataFreshness(transactionsResult, forceFullRefresh),
-            data_source: getAuditDataSource(transactionsResult, forceFullRefresh),
+            data_freshness: "guaranteed_fresh",
+            data_source: "full_api_fetch_no_delta",
             server_knowledge: transactionsResult.serverKnowledge,
             fetched_at: new Date().toISOString(),
             accounts_count: accountResult.data.length,
@@ -300,8 +282,14 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             uncleared_balance: accountData.uncleared_balance,
         };
         const analysis = analyzeReconciliation(parseResult, params.csv_file_path, ynabTransactions, adjustedStatementBalance, config, currencyCode, params.account_id, params.budget_id, finalInvertAmounts, csvOptions, initialAccount);
+        const effectiveParams = effectiveStatementEndDate !== params.statement_end_date
+            ? {
+                ...params,
+                statement_end_date: effectiveStatementEndDate,
+            }
+            : params;
         let executionData;
-        const wantsBalanceVerification = Boolean(params.statement_date);
+        const wantsBalanceVerification = Boolean(effectiveParams.statement_end_date);
         const shouldExecute = params.auto_create_transactions ||
             params.auto_update_cleared_status ||
             params.auto_unclear_missing ||
@@ -311,7 +299,7 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             executionData = await executeReconciliation({
                 ynabAPI,
                 analysis,
-                params,
+                params: effectiveParams,
                 budgetId: params.budget_id,
                 accountId: params.account_id,
                 initialAccount,
@@ -335,22 +323,35 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             adapterOptions.notes = narrativeNotes;
         }
         const payload = buildReconciliationPayload(analysis, adapterOptions, executionData);
+        let executionSummary;
+        if (executionData) {
+            const balanceRecon = executionData.balance_reconciliation;
+            const balanceStatus = !wantsBalanceVerification
+                ? "not_verified"
+                : balanceRecon?.status === "balanced"
+                    ? "balanced"
+                    : "unbalanced";
+            executionSummary = {
+                transactions_created: executionData.summary.transactions_created,
+                transactions_updated: executionData.summary.transactions_updated,
+                dates_adjusted: executionData.summary.dates_adjusted,
+                dry_run: executionData.summary.dry_run,
+                balance_status: balanceStatus,
+                recommendations: executionData.recommendations,
+            };
+        }
+        const structured = {
+            unmatched_bank: payload.structured.unmatched.bank,
+            unmatched_ynab: payload.structured.unmatched.ynab,
+            suggestions: payload.structured.matches.suggested,
+            ...(executionSummary !== undefined && {
+                execution_summary: executionSummary,
+            }),
+        };
         const responseData = {
             human: payload.human,
+            structured,
         };
-        if (params.include_structured_data) {
-            if (params.structured_content === "unmatched_only") {
-                const filteredStructured = {
-                    unmatched_bank: payload.structured.unmatched.bank,
-                    unmatched_ynab: payload.structured.unmatched.ynab,
-                    suggestions: payload.structured.matches.suggested,
-                };
-                responseData["structured"] = filteredStructured;
-            }
-            else {
-                responseData["structured"] = payload.structured;
-            }
-        }
         return {
             content: [
                 {
@@ -398,17 +399,15 @@ Args:
   - csv_file_path or csv_data (string, required): Bank export file path or inline CSV text.
   - statement_balance (number, required): Ending balance from the bank statement (dollars).
       For credit cards and other liability accounts, pass a negative value (e.g. -6143.27 means you owe $6,143.27).
+  - statement_end_date (string, optional): Statement closing date (YYYY-MM-DD). Filters CSV and triggers balance verification. Auto-detected from CSV if omitted.
+  - match_strictness (string, optional): Matching sensitivity — "loose" (more matches), "normal" (default), or "strict" (fewer false positives).
+  - sign_convention (string, optional): How to treat CSV amount signs — "auto" (default, detects from data), "invert" (negate all amounts), "as_is" (use amounts unchanged). Useful when auto-detection fails for liability accounts.
   - dry_run (boolean, optional): Preview actions without executing. Default: true.
   - auto_create_transactions (boolean, optional): Auto-create missing transactions. Default: false.
   - auto_update_cleared_status (boolean, optional): Auto-mark matched transactions as cleared. Default: false.
-  - auto_match_threshold (number, optional): Score 0–100 required for automatic matching. Default: 85.
-      Lower to 70–75 to match more transactions automatically; raise to 90+ for stricter matching.
-  - include_structured_data (boolean, optional): Include full JSON output alongside narrative. Default: false.
-  - structured_content (string, optional): "full" or "unmatched_only". Default: "full".
-  - max_suggestions_in_output (number, optional): Limit unmatched items and suggestions shown in the human report.
-      Default: 20.
+  - max_suggestions_in_output (number, optional): Limit unmatched items and suggestions shown in the human report. Default: 20.
 
-Returns: human-readable reconciliation narrative; optionally structured JSON data.
+Returns: human-readable reconciliation narrative + structured JSON (unmatched_bank, unmatched_ynab, suggestions, execution_summary when actions are performed).
 
 Examples:
   - Preview reconciliation: set dry_run=true (default)
@@ -443,6 +442,15 @@ function mapCsvDateFormatToHint(format) {
     }
     return undefined;
 }
+function inferLatestTransactionDate(transactions) {
+    let latestDate;
+    for (const transaction of transactions) {
+        if (latestDate === undefined || transaction.date > latestDate) {
+            latestDate = transaction.date;
+        }
+    }
+    return latestDate;
+}
 function mapCsvFormatForPayload(format) {
     if (!format) {
         return undefined;