@stephendolan/ynab-cli 2.7.0 → 2.8.1

package/dist/cli.js

@@ -187,6 +187,92 @@ function applyTransactionFilters(transactions, filters) {
   }
   return filtered;
 }
+function summarizeTransactions(transactions, options) {
+  let totalAmount = 0;
+  const dates = [];
+  const byPayee = /* @__PURE__ */ new Map();
+  const byCategory = /* @__PURE__ */ new Map();
+  const byCleared = /* @__PURE__ */ new Map();
+  const byApproval = /* @__PURE__ */ new Map();
+  for (const t of transactions) {
+    totalAmount += t.amount;
+    dates.push(t.date);
+    const payeeKey = t.payee_id || t.payee_name || "(none)";
+    const payeeEntry = byPayee.get(payeeKey) || {
+      payee_id: t.payee_id || null,
+      payee_name: t.payee_name || null,
+      count: 0,
+      total_amount: 0
+    };
+    payeeEntry.count++;
+    payeeEntry.total_amount += t.amount;
+    byPayee.set(payeeKey, payeeEntry);
+    const catKey = t.category_id || t.category_name || "(uncategorized)";
+    const catEntry = byCategory.get(catKey) || {
+      category_id: t.category_id || null,
+      category_name: t.category_name || null,
+      count: 0,
+      total_amount: 0
+    };
+    catEntry.count++;
+    catEntry.total_amount += t.amount;
+    byCategory.set(catKey, catEntry);
+    const clearedEntry = byCleared.get(t.cleared) || { count: 0, total_amount: 0 };
+    clearedEntry.count++;
+    clearedEntry.total_amount += t.amount;
+    byCleared.set(t.cleared, clearedEntry);
+    const approvalKey = String(t.approved);
+    const approvalEntry = byApproval.get(approvalKey) || { count: 0, total_amount: 0 };
+    approvalEntry.count++;
+    approvalEntry.total_amount += t.amount;
+    byApproval.set(approvalKey, approvalEntry);
+  }
+  const sortByAbsAmount = (entries) => entries.sort((a, b) => Math.abs(b.total_amount) - Math.abs(a.total_amount));
+  const truncate = (entries, rollupFactory) => {
+    const top = options?.top;
+    if (!top || top <= 0 || entries.length <= top) return entries;
+    const kept = entries.slice(0, top);
+    const rest = entries.slice(top);
+    const rollup = rollupFactory({
+      count: rest.reduce((sum, e) => sum + e.count, 0),
+      total_amount: rest.reduce((sum, e) => sum + e.total_amount, 0)
+    });
+    return [...kept, rollup];
+  };
+  const payeeBreakdown = sortByAbsAmount([...byPayee.values()]);
+  const categoryBreakdown = sortByAbsAmount([...byCategory.values()]);
+  return {
+    total_count: transactions.length,
+    total_amount: totalAmount,
+    date_range: dates.length > 0 ? {
+      from: dates.reduce((a, b) => a < b ? a : b),
+      to: dates.reduce((a, b) => a > b ? a : b)
+    } : null,
+    by_payee: truncate(payeeBreakdown, (e) => ({ payee_id: null, payee_name: "(other)", ...e })),
+    by_category: truncate(categoryBreakdown, (e) => ({ category_id: null, category_name: "(other)", ...e })),
+    by_cleared_status: [...byCleared.entries()].map(([status, entry]) => ({ status, ...entry })),
+    by_approval_status: [...byApproval.entries()].map(([approved, entry]) => ({ approved: approved === "true", ...entry }))
+  };
+}
+function findTransferCandidates(source, allTransactions, options) {
+  const sourceAmount = Math.abs(source.amount);
+  const sourceDateMs = new Date(source.date).getTime();
+  const msPerDay = 864e5;
+  function daysBetween(t) {
+    return Math.abs(new Date(t.date).getTime() - sourceDateMs) / msPerDay;
+  }
+  return allTransactions.filter((t) => {
+    if (t.account_id === source.account_id) return false;
+    if (Math.abs(t.amount) !== sourceAmount) return false;
+    if (Math.sign(t.amount) === Math.sign(source.amount)) return false;
+    return daysBetween(t) <= options.maxDays;
+  }).map((t) => ({
+    transaction: t,
+    already_linked: !!t.transfer_transaction_id,
+    date_difference_days: Math.round(daysBetween(t)),
+    has_transfer_payee: !!t.payee_name?.startsWith("Transfer :")
+  })).sort((a, b) => a.date_difference_days - b.date_difference_days);
+}
 function applyFieldSelection(items, fields) {
   if (!fields) return items;
   const fieldList = fields.split(",").map((f) => f.trim());
@@ -352,338 +438,271 @@ var YnabClient = class {
     }
     return budgetId;
   }
-  async withErrorHandling(fn) {
-    try {
-      return await fn();
-    } catch (error) {
-      handleYnabError(error);
-    }
-  }
   async getUser() {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const response = await api.user.getUser();
-      return response.data.user;
-    });
+    const api = await this.getApi();
+    const response = await api.user.getUser();
+    return response.data.user;
   }
   async getBudgets(includeAccounts = false) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const response = await api.budgets.getBudgets(includeAccounts);
-      return {
-        budgets: response.data.budgets,
-        server_knowledge: 0
-      };
-    });
+    const api = await this.getApi();
+    const response = await api.budgets.getBudgets(includeAccounts);
+    return {
+      budgets: response.data.budgets,
+      server_knowledge: 0
+    };
   }
   async getBudget(budgetId, lastKnowledgeOfServer) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.budgets.getBudgetById(id, lastKnowledgeOfServer);
-      return {
-        budget: response.data.budget,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.budgets.getBudgetById(id, lastKnowledgeOfServer);
+    return {
+      budget: response.data.budget,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getBudgetSettings(budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.budgets.getBudgetSettingsById(id);
-      return response.data.settings;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.budgets.getBudgetSettingsById(id);
+    return response.data.settings;
   }
   async getAccounts(budgetId, lastKnowledgeOfServer) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.accounts.getAccounts(id, lastKnowledgeOfServer);
-      return {
-        accounts: response.data.accounts,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.accounts.getAccounts(id, lastKnowledgeOfServer);
+    return {
+      accounts: response.data.accounts,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getAccount(accountId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.accounts.getAccountById(id, accountId);
-      return response.data.account;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.accounts.getAccountById(id, accountId);
+    return response.data.account;
   }
   async getCategories(budgetId, lastKnowledgeOfServer) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.categories.getCategories(id, lastKnowledgeOfServer);
-      return {
-        category_groups: response.data.category_groups,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.categories.getCategories(id, lastKnowledgeOfServer);
+    return {
+      category_groups: response.data.category_groups,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getCategory(categoryId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.categories.getCategoryById(id, categoryId);
-      return response.data.category;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.categories.getCategoryById(id, categoryId);
+    return response.data.category;
   }
   async updateMonthCategory(month, categoryId, data, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.categories.updateMonthCategory(id, month, categoryId, data);
-      return response.data.category;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.categories.updateMonthCategory(id, month, categoryId, data);
+    return response.data.category;
   }
   async updateCategory(categoryId, data, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.categories.updateCategory(id, categoryId, data);
-      return response.data.category;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.categories.updateCategory(id, categoryId, data);
+    return response.data.category;
   }
   async getPayees(budgetId, lastKnowledgeOfServer) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.payees.getPayees(id, lastKnowledgeOfServer);
-      return {
-        payees: response.data.payees,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.payees.getPayees(id, lastKnowledgeOfServer);
+    return {
+      payees: response.data.payees,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getPayee(payeeId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.payees.getPayeeById(id, payeeId);
-      return response.data.payee;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.payees.getPayeeById(id, payeeId);
+    return response.data.payee;
   }
   async updatePayee(payeeId, data, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.payees.updatePayee(id, payeeId, data);
-      return response.data.payee;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.payees.updatePayee(id, payeeId, data);
+    return response.data.payee;
   }
   async getPayeeLocationsByPayee(payeeId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.payeeLocations.getPayeeLocationsByPayee(id, payeeId);
-      return response.data.payee_locations;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.payeeLocations.getPayeeLocationsByPayee(id, payeeId);
+    return response.data.payee_locations;
   }
   async getBudgetMonths(budgetId, lastKnowledgeOfServer) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.months.getBudgetMonths(id, lastKnowledgeOfServer);
-      return {
-        months: response.data.months,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.months.getBudgetMonths(id, lastKnowledgeOfServer);
+    return {
+      months: response.data.months,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getBudgetMonth(month, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.months.getBudgetMonth(id, month);
-      return response.data.month;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.months.getBudgetMonth(id, month);
+    return response.data.month;
   }
   async getTransactions(params) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(params.budgetId);
-      const response = await api.transactions.getTransactions(
-        id,
-        params.sinceDate,
-        params.type,
-        params.lastKnowledgeOfServer
-      );
-      return {
-        transactions: response.data.transactions,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(params.budgetId);
+    const response = await api.transactions.getTransactions(
+      id,
+      params.sinceDate,
+      params.type,
+      params.lastKnowledgeOfServer
+    );
+    return {
+      transactions: response.data.transactions,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getTransactionsByAccount(accountId, params) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(params.budgetId);
-      const response = await api.transactions.getTransactionsByAccount(
-        id,
-        accountId,
-        params.sinceDate,
-        params.type,
-        params.lastKnowledgeOfServer
-      );
-      return {
-        transactions: response.data.transactions,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(params.budgetId);
+    const response = await api.transactions.getTransactionsByAccount(
+      id,
+      accountId,
+      params.sinceDate,
+      params.type,
+      params.lastKnowledgeOfServer
+    );
+    return {
+      transactions: response.data.transactions,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getTransactionsByCategory(categoryId, params) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(params.budgetId);
-      const response = await api.transactions.getTransactionsByCategory(
-        id,
-        categoryId,
-        params.sinceDate,
-        params.type,
-        params.lastKnowledgeOfServer
-      );
-      return {
-        transactions: response.data.transactions,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(params.budgetId);
+    const response = await api.transactions.getTransactionsByCategory(
+      id,
+      categoryId,
+      params.sinceDate,
+      params.type,
+      params.lastKnowledgeOfServer
+    );
+    return {
+      transactions: response.data.transactions,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getTransactionsByPayee(payeeId, params) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(params.budgetId);
-      const response = await api.transactions.getTransactionsByPayee(
-        id,
-        payeeId,
-        params.sinceDate,
-        params.type,
-        params.lastKnowledgeOfServer
-      );
-      return {
-        transactions: response.data.transactions,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(params.budgetId);
+    const response = await api.transactions.getTransactionsByPayee(
+      id,
+      payeeId,
+      params.sinceDate,
+      params.type,
+      params.lastKnowledgeOfServer
+    );
+    return {
+      transactions: response.data.transactions,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getTransaction(transactionId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.transactions.getTransactionById(id, transactionId);
-      return response.data.transaction;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.transactions.getTransactionById(id, transactionId);
+    return response.data.transaction;
   }
   async createTransaction(transactionData, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.transactions.createTransaction(id, transactionData);
-      return response.data.transaction;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.transactions.createTransaction(id, transactionData);
+    return response.data.transaction;
   }
   async updateTransaction(transactionId, transactionData, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.transactions.updateTransaction(id, transactionId, transactionData);
-      return response.data.transaction;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.transactions.updateTransaction(id, transactionId, transactionData);
+    return response.data.transaction;
   }
   async updateTransactions(transactions, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.transactions.updateTransactions(id, transactions);
-      return {
-        transactions: response.data.transactions,
-        transaction_ids: response.data.transaction_ids,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.transactions.updateTransactions(id, transactions);
+    return {
+      transactions: response.data.transactions,
+      transaction_ids: response.data.transaction_ids,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async deleteTransaction(transactionId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.transactions.deleteTransaction(id, transactionId);
-      return response.data.transaction;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.transactions.deleteTransaction(id, transactionId);
+    return response.data.transaction;
   }
   async importTransactions(budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.transactions.importTransactions(id);
-      return response.data.transaction_ids;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.transactions.importTransactions(id);
+    return response.data.transaction_ids;
   }
   async getScheduledTransactions(budgetId, lastKnowledgeOfServer) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.scheduledTransactions.getScheduledTransactions(
-        id,
-        lastKnowledgeOfServer
-      );
-      return {
-        scheduled_transactions: response.data.scheduled_transactions,
-        server_knowledge: response.data.server_knowledge
-      };
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.scheduledTransactions.getScheduledTransactions(
+      id,
+      lastKnowledgeOfServer
+    );
+    return {
+      scheduled_transactions: response.data.scheduled_transactions,
+      server_knowledge: response.data.server_knowledge
+    };
   }
   async getScheduledTransaction(scheduledTransactionId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.scheduledTransactions.getScheduledTransactionById(
-        id,
-        scheduledTransactionId
-      );
-      return response.data.scheduled_transaction;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.scheduledTransactions.getScheduledTransactionById(
+      id,
+      scheduledTransactionId
+    );
+    return response.data.scheduled_transaction;
   }
   async deleteScheduledTransaction(scheduledTransactionId, budgetId) {
-    return this.withErrorHandling(async () => {
-      const api = await this.getApi();
-      const id = await this.getBudgetId(budgetId);
-      const response = await api.scheduledTransactions.deleteScheduledTransaction(
-        id,
-        scheduledTransactionId
-      );
-      return response.data.scheduled_transaction;
-    });
+    const api = await this.getApi();
+    const id = await this.getBudgetId(budgetId);
+    const response = await api.scheduledTransactions.deleteScheduledTransaction(
+      id,
+      scheduledTransactionId
+    );
+    return response.data.scheduled_transaction;
   }
   async rawApiCall(method, path, data, budgetId) {
-    return this.withErrorHandling(async () => {
-      await this.getApi();
-      const fullPath = path.includes("{budget_id}") ? path.replace("{budget_id}", await this.getBudgetId(budgetId)) : path;
-      const url = `https://api.ynab.com/v1${fullPath}`;
-      const accessToken = await auth.getAccessToken() || process.env.YNAB_API_KEY;
-      const headers = {
-        Authorization: `Bearer ${accessToken}`,
-        "Content-Type": "application/json"
-      };
-      const httpMethod = method.toUpperCase();
-      const hasBody = ["POST", "PUT", "PATCH"].includes(httpMethod);
-      if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(httpMethod)) {
-        throw new YnabCliError(`Unsupported HTTP method: ${method}`, 400);
-      }
-      const response = await fetch(url, {
-        method: httpMethod,
-        headers,
-        ...hasBody && { body: JSON.stringify(data) }
-      });
-      if (!response.ok) {
-        const errorData = await response.json();
-        throw { error: sanitizeApiError(errorData.error || errorData) };
-      }
-      return await response.json();
+    await this.getApi();
+    const fullPath = path.includes("{budget_id}") ? path.replace("{budget_id}", await this.getBudgetId(budgetId)) : path;
+    const url = `https://api.ynab.com/v1${fullPath}`;
+    const accessToken = await auth.getAccessToken() || process.env.YNAB_API_KEY;
+    const headers = {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json"
+    };
+    const httpMethod = method.toUpperCase();
+    const hasBody = ["POST", "PUT", "PATCH"].includes(httpMethod);
+    if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(httpMethod)) {
+      throw new YnabCliError(`Unsupported HTTP method: ${method}`, 400);
+    }
+    const response = await fetch(url, {
+      method: httpMethod,
+      headers,
+      ...hasBody && { body: JSON.stringify(data) }
     });
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw { error: sanitizeApiError(errorData.error || errorData) };
+    }
+    return await response.json();
   }
 };
 var client = new YnabClient();
@@ -986,6 +1005,7 @@ function createCategoriesCommand() {
 
 // src/commands/transactions.ts
 import { Command as Command6 } from "commander";
+import dayjs2 from "dayjs";
 
 // src/lib/schemas.ts
 function validateTransactionSplits(data) {
@@ -1054,6 +1074,18 @@ function validateApiData(data) {
 }
 
 // src/commands/transactions.ts
+async function fetchTransactions(options) {
+  const params = {
+    budgetId: options.budget,
+    sinceDate: options.since ? parseDate(options.since) : void 0,
+    type: options.type,
+    lastKnowledgeOfServer: options.lastKnowledge
+  };
+  if (options.account) return client.getTransactionsByAccount(options.account, params);
+  if (options.category) return client.getTransactionsByCategory(options.category, params);
+  if (options.payee) return client.getTransactionsByPayee(options.payee, params);
+  return client.getTransactions(params);
+}
 function buildTransactionData(options) {
   if (!options.account) {
     throw new YnabCliError("--account is required in non-interactive mode", 400);
@@ -1081,25 +1113,27 @@ function createTransactionsCommand() {
   ).option("--min-amount <amount>", "Minimum amount in currency units (e.g., 10.50)", parseFloat).option("--max-amount <amount>", "Maximum amount in currency units (e.g., 100.00)", parseFloat).option(
     "--fields <fields>",
     "Comma-separated list of fields to include (e.g., id,date,amount,memo)"
-  ).action(
+  ).option("--last-knowledge <number>", "Last server knowledge for delta requests. When used, output includes server_knowledge.", parseInt).option("--limit <number>", "Maximum number of transactions to return", parseInt).action(
     withErrorHandling(
       async (options) => {
-        const params = {
-          budgetId: options.budget,
-          sinceDate: options.since ? parseDate(options.since) : void 0,
-          type: options.type
-        };
-        const result = options.account ? await client.getTransactionsByAccount(options.account, params) : options.category ? await client.getTransactionsByCategory(options.category, params) : options.payee ? await client.getTransactionsByPayee(options.payee, params) : await client.getTransactions(params);
+        const result = await fetchTransactions(options);
         const transactions = result?.transactions || [];
-        const filtered = applyTransactionFilters(transactions, {
+        let filtered = applyTransactionFilters(transactions, {
           until: options.until ? parseDate(options.until) : void 0,
           approved: options.approved,
           status: options.status,
           minAmount: options.minAmount,
           maxAmount: options.maxAmount
         });
+        if (options.limit && options.limit > 0) {
+          filtered = filtered.slice(0, options.limit);
+        }
         const selected = applyFieldSelection(filtered, options.fields);
-        outputJson(selected);
+        if (options.lastKnowledge !== void 0) {
+          outputJson({ transactions: selected, server_knowledge: result?.server_knowledge });
+        } else {
+          outputJson(selected);
+        }
       }
     )
   );
@@ -1294,6 +1328,49 @@ function createTransactionsCommand() {
       }
     )
   );
+  cmd.command("summary").description("Summarize transactions with aggregate counts by payee, category, and status").option("-b, --budget <id>", "Budget ID").option("--account <id>", "Filter by account ID").option("--category <id>", "Filter by category ID").option("--payee <id>", "Filter by payee ID").option("--since <date>", "Filter transactions since date").option("--until <date>", "Filter transactions until date").option("--type <type>", "Filter by transaction type").option("--approved <value>", "Filter by approval status: true or false").option(
+    "--status <statuses>",
+    "Filter by cleared status: cleared, uncleared, reconciled (comma-separated)"
+  ).option("--min-amount <amount>", "Minimum amount in currency units", parseFloat).option("--max-amount <amount>", "Maximum amount in currency units", parseFloat).option("--top <number>", "Limit payee/category breakdowns to top N entries", parseInt).action(
+    withErrorHandling(
+      async (options) => {
+        const result = await fetchTransactions(options);
+        const transactions = result?.transactions || [];
+        const filtered = applyTransactionFilters(transactions, {
+          until: options.until ? parseDate(options.until) : void 0,
+          approved: options.approved,
+          status: options.status,
+          minAmount: options.minAmount,
+          maxAmount: options.maxAmount
+        });
+        const summary = summarizeTransactions(
+          filtered,
+          options.top ? { top: options.top } : void 0
+        );
+        outputJson(summary);
+      }
+    )
+  );
+  cmd.command("find-transfers").description("Find candidate transfer matches for a transaction across accounts").argument("<id>", "Transaction ID").option("-b, --budget <id>", "Budget ID").option("--days <number>", "Maximum date difference in days (default: 3)", parseInt).option("--since <date>", "Search transactions since date (defaults to source date minus --days)").action(
+    withErrorHandling(
+      async (id, options) => {
+        const maxDays = options.days ?? 3;
+        const source = await client.getTransaction(id, options.budget);
+        const sinceDate = options.since ? parseDate(options.since) : dayjs2(source.date).subtract(maxDays, "day").format("YYYY-MM-DD");
+        const result = await client.getTransactions({
+          budgetId: options.budget,
+          sinceDate
+        });
+        const allTransactions = result?.transactions || [];
+        const candidates = findTransferCandidates(
+          source,
+          allTransactions,
+          { maxDays }
+        );
+        outputJson({ source, candidates });
+      }
+    )
+  );
   return cmd;
 }
 
@@ -1470,6 +1547,8 @@ var toolRegistry = [
   { name: "delete_transaction", description: "Delete a transaction" },
   { name: "import_transactions", description: "Trigger import of linked bank transactions" },
   { name: "batch_update_transactions", description: "Update multiple transactions in a single API call" },
+  { name: "summarize_transactions", description: "Get aggregate summary of transactions by payee, category, and status" },
+  { name: "find_transfer_candidates", description: "Find candidate transfer matches for a transaction across accounts" },
   { name: "list_transactions_by_account", description: "List transactions for a specific account" },
   { name: "list_transactions_by_category", description: "List transactions for a specific category" },
   { name: "list_transactions_by_payee", description: "List transactions for a specific payee" },
@@ -1489,6 +1568,37 @@ var server = new McpServer({
   name: "ynab",
   version: "1.0.0"
 });
+function mcpErrorResult(error) {
+  let errorBody;
+  if (typeof error === "object" && error !== null && "error" in error) {
+    const apiError = sanitizeApiError(error.error);
+    errorBody = { name: apiError.name, detail: apiError.detail };
+  } else if (error instanceof YnabCliError) {
+    errorBody = { name: "cli_error", detail: sanitizeErrorMessage(error.message) };
+  } else if (error instanceof Error) {
+    errorBody = { name: error.name, detail: sanitizeErrorMessage(error.message) };
+  } else {
+    errorBody = { name: "unknown_error", detail: "An unexpected error occurred" };
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: errorBody }) }],
+    isError: true
+  };
+}
+var _serverTool = server.tool.bind(server);
+server.tool = (...args) => {
+  const handler = args[args.length - 1];
+  if (typeof handler === "function") {
+    args[args.length - 1] = async (...handlerArgs) => {
+      try {
+        return await handler(...handlerArgs);
+      } catch (error) {
+        return mcpErrorResult(error);
+      }
+    };
+  }
+  return _serverTool.apply(null, args);
+};
 function jsonResponse(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
@@ -1582,9 +1692,18 @@ server.tool(
   {
     budgetId: z.string().optional().describe("Budget ID (uses default if not specified)"),
     sinceDate: z.string().optional().describe("Only return transactions on or after this date (YYYY-MM-DD)"),
-    type: z.enum(["uncategorized", "unapproved"]).optional().describe("Filter by transaction type")
+    type: z.enum(["uncategorized", "unapproved"]).optional().describe("Filter by transaction type"),
+    lastKnowledgeOfServer: z.number().optional().describe("Delta sync: only return changes since this server knowledge value. Response includes server_knowledge for next call."),
+    limit: z.number().optional().describe("Maximum number of transactions to return"),
+    fields: z.string().optional().describe("Comma-separated list of fields to include (e.g., id,date,amount,memo)")
   },
-  async ({ budgetId, sinceDate, type }) => currencyResponse(await client.getTransactions({ budgetId, sinceDate, type }))
+  async ({ budgetId, sinceDate, type, lastKnowledgeOfServer, limit, fields }) => {
+    const result = await client.getTransactions({ budgetId, sinceDate, type, lastKnowledgeOfServer });
+    let transactions = result?.transactions || [];
+    if (limit && limit > 0) transactions = transactions.slice(0, limit);
+    const selected = fields ? applyFieldSelection(transactions, fields) : transactions;
+    return currencyResponse({ transactions: selected, server_knowledge: result?.server_knowledge });
+  }
 );
 server.tool(
   "get_transaction",
@@ -1703,6 +1822,64 @@ server.tool(
     );
   }
 );
+server.tool(
+  "summarize_transactions",
+  "Get aggregate summary of transactions by payee, category, and status",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not specified)"),
+    sinceDate: z.string().optional().describe("Only return transactions on or after this date (YYYY-MM-DD)"),
+    untilDate: z.string().optional().describe("Only return transactions on or before this date (YYYY-MM-DD)"),
+    type: z.enum(["uncategorized", "unapproved"]).optional().describe("Filter by transaction type"),
+    approved: z.enum(["true", "false"]).optional().describe("Filter by approval status"),
+    status: z.string().optional().describe("Filter by cleared status: cleared, uncleared, reconciled (comma-separated)"),
+    minAmount: z.number().optional().describe("Minimum amount in dollars"),
+    maxAmount: z.number().optional().describe("Maximum amount in dollars"),
+    top: z.number().optional().describe("Limit payee/category breakdowns to top N entries")
+  },
+  async ({ budgetId, sinceDate, untilDate, type, approved, status, minAmount, maxAmount, top }) => {
+    const result = await client.getTransactions({ budgetId, sinceDate, type });
+    const transactions = result?.transactions || [];
+    const filtered = applyTransactionFilters(transactions, {
+      until: untilDate,
+      approved,
+      status,
+      minAmount,
+      maxAmount
+    });
+    const summary = summarizeTransactions(
+      filtered,
+      top ? { top } : void 0
+    );
+    return currencyResponse(summary);
+  }
+);
+server.tool(
+  "find_transfer_candidates",
+  "Find candidate transfer matches for a transaction across accounts",
+  {
+    transactionId: z.string().describe("Transaction ID to find transfers for"),
+    budgetId: z.string().optional().describe("Budget ID (uses default if not specified)"),
+    maxDays: z.number().optional().describe("Maximum date difference in days (default: 3)"),
+    sinceDate: z.string().optional().describe("Search transactions since date (defaults to source date minus maxDays)")
+  },
+  async ({ transactionId, budgetId, maxDays: maxDaysParam, sinceDate }) => {
+    const days = maxDaysParam ?? 3;
+    const source = await client.getTransaction(transactionId, budgetId);
+    if (!sinceDate) {
+      const d = new Date(source.date);
+      d.setDate(d.getDate() - days);
+      sinceDate = d.toISOString().split("T")[0];
+    }
+    const result = await client.getTransactions({ budgetId, sinceDate });
+    const allTransactions = result?.transactions || [];
+    const candidates = findTransferCandidates(
+      source,
+      allTransactions,
+      { maxDays: days }
+    );
+    return currencyResponse({ source, candidates });
+  }
+);
 server.tool(
   "list_transactions_by_account",
   "List transactions for a specific account",
@@ -1867,7 +2044,7 @@ function createMcpCommand() {
 
 // src/cli.ts
 var program = new Command12();
-program.name("ynab").description("A command-line interface for You Need a Budget (YNAB)").version("2.7.0").option("-c, --compact", "Minified JSON output (single line)").hook("preAction", (thisCommand) => {
+program.name("ynab").description("A command-line interface for You Need a Budget (YNAB)").version("2.8.1").option("-c, --compact", "Minified JSON output (single line)").hook("preAction", (thisCommand) => {
   const options = thisCommand.opts();
   setOutputOptions({
     compact: options.compact