@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/compareTransactions/parser.js

@@ -0,0 +1,430 @@
+import { parse } from 'csv-parse/sync';
+import { parse as parseDateFns } from 'date-fns';
+import { toMilli } from '../../utils/money.js';
+import { readFileSync } from 'fs';
+export function parseDate(dateStr, format) {
+    const cleanDate = dateStr.trim();
+    const formatMap = {
+        'MM/DD/YYYY': 'MM/dd/yyyy',
+        'M/D/YYYY': 'M/d/yyyy',
+        'DD/MM/YYYY': 'dd/MM/yyyy',
+        'D/M/YYYY': 'd/M/yyyy',
+        'YYYY-MM-DD': 'yyyy-MM-dd',
+        'MM-DD-YYYY': 'MM-dd-yyyy',
+        'MMM dd, yyyy': 'MMM dd, yyyy',
+        'MMM d, yyyy': 'MMM d, yyyy',
+    };
+    const dateFnsFormat = formatMap[format];
+    if (dateFnsFormat) {
+        try {
+            const parsed = parseDateFns(cleanDate, dateFnsFormat, new Date());
+            if (!isNaN(parsed.getTime())) {
+                return parsed;
+            }
+        }
+        catch {
+        }
+    }
+    const parsed = new Date(cleanDate);
+    if (isNaN(parsed.getTime())) {
+        throw new Error(`Unable to parse date: ${dateStr} with format: ${format}`);
+    }
+    return parsed;
+}
+export function amountToMilliunits(amountStr) {
+    const cleaned = amountStr.replace(/[$,\s]/g, '').trim();
+    let s = cleaned, neg = false;
+    if (s.startsWith('(') && s.endsWith(')')) {
+        neg = true;
+        s = s.slice(1, -1);
+    }
+    if (s.startsWith('+'))
+        s = s.slice(1);
+    const n = Number(s);
+    if (isNaN(n) || !isFinite(n)) {
+        throw new Error(`Invalid amount value: "${amountStr}" (cleaned: "${s}")`);
+    }
+    return toMilli(neg ? -n : n);
+}
+function isDateLike(str) {
+    if (!str)
+        return false;
+    const datePatterns = [
+        /^\d{1,2}\/\d{1,2}\/\d{4}$/,
+        /^\d{4}-\d{1,2}-\d{1,2}$/,
+        /^\d{1,2}-\d{1,2}-\d{4}$/,
+        /^[A-Za-z]{3}\s+\d{1,2},\s+\d{4}$/,
+    ];
+    return datePatterns.some((pattern) => pattern.test(str.trim()));
+}
+export function detectDateFormat(dateStr) {
+    if (!dateStr)
+        return 'MM/DD/YYYY';
+    const cleaned = dateStr.trim();
+    if (cleaned.includes('/')) {
+        return 'MM/DD/YYYY';
+    }
+    else if (cleaned.includes('-')) {
+        if (/^\d{4}-/.test(cleaned)) {
+            return 'YYYY-MM-DD';
+        }
+        else {
+            return 'MM-DD-YYYY';
+        }
+    }
+    else if (/^[A-Za-z]{3}\s+\d{1,2},\s+\d{4}$/.test(cleaned)) {
+        return 'MMM dd, yyyy';
+    }
+    return 'MM/DD/YYYY';
+}
+function detectDelimiter(lines) {
+    const candidates = [',', ';', '\t', '|'];
+    const sampleLines = lines.slice(0, 3).filter((line) => line.trim());
+    if (sampleLines.length === 0) {
+        return ',';
+    }
+    let bestDelimiter = ',';
+    let bestScore = -1;
+    for (const delimiter of candidates) {
+        let score = 0;
+        const columnCounts = [];
+        let parseFailed = false;
+        for (const line of sampleLines) {
+            try {
+                const rows = parse(line, {
+                    delimiter,
+                    quote: '"',
+                    escape: '"',
+                    skip_empty_lines: true,
+                    trim: true,
+                    relax_column_count: true,
+                });
+                if (rows && rows.length > 0 && rows[0]) {
+                    const columns = Array.isArray(rows[0]) ? rows[0] : Object.values(rows[0]);
+                    columnCounts.push(columns.length);
+                }
+                else {
+                    const columns = line.split(delimiter);
+                    columnCounts.push(columns.length);
+                }
+            }
+            catch {
+                parseFailed = true;
+                const columns = line.split(delimiter);
+                columnCounts.push(columns.length);
+            }
+        }
+        if (columnCounts.length > 1) {
+            const firstCount = columnCounts[0];
+            if (firstCount === undefined)
+                continue;
+            const isConsistent = columnCounts.every((count) => count === firstCount);
+            if (isConsistent && firstCount > 1) {
+                score = Math.min(firstCount, 10);
+                if (delimiter === ',')
+                    score += 0.5;
+                if (delimiter === ';')
+                    score += 0.3;
+                if (!parseFailed)
+                    score += 0.2;
+            }
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestDelimiter = delimiter;
+        }
+    }
+    return bestDelimiter;
+}
+function analyzeHeaders(headers) {
+    const datePattern = /^(date|trans.*date|transaction.*date|post.*date|dt)$/i;
+    const amountPattern = /^(amount|amt|dollar.*amount|transaction.*amount)$/i;
+    const descriptionPattern = /^(description|desc|memo|transaction.*description|payee|merchant)$/i;
+    const debitPattern = /^(debit|debits|withdrawal|withdrawals|out|outgoing)$/i;
+    const creditPattern = /^(credit|credits|deposit|deposits|in|incoming)$/i;
+    let dateColumn = null;
+    let amountColumn = null;
+    let descriptionColumn = null;
+    let debitColumn = null;
+    let creditColumn = null;
+    for (const header of headers) {
+        const cleanHeader = header.trim();
+        if (datePattern.test(cleanHeader)) {
+            dateColumn = cleanHeader;
+        }
+        else if (amountPattern.test(cleanHeader)) {
+            amountColumn = cleanHeader;
+        }
+        else if (descriptionPattern.test(cleanHeader)) {
+            descriptionColumn = cleanHeader;
+        }
+        else if (debitPattern.test(cleanHeader)) {
+            debitColumn = cleanHeader;
+        }
+        else if (creditPattern.test(cleanHeader)) {
+            creditColumn = cleanHeader;
+        }
+    }
+    return { dateColumn, amountColumn, descriptionColumn, debitColumn, creditColumn };
+}
+export function autoDetectCSVFormat(csvContent) {
+    const linesRaw = csvContent.trim().split('\n').slice(0, 3);
+    if (linesRaw.length === 0) {
+        throw new Error('CSV file is empty');
+    }
+    const firstLineRaw = linesRaw[0];
+    if (!firstLineRaw || !firstLineRaw.trim()) {
+        throw new Error('CSV file contains empty first line');
+    }
+    const delimiter = detectDelimiter(linesRaw);
+    const firstLine = firstLineRaw.split(delimiter);
+    const hasHeader = !isDateLike(firstLine[0] || '');
+    let hasDebitCredit = false;
+    if (linesRaw.length > 1) {
+        const dataLines = hasHeader ? linesRaw.slice(1) : linesRaw;
+        hasDebitCredit = dataLines.some((line) => {
+            const cols = line.split(delimiter);
+            return (cols.length >= 4 &&
+                ((cols[2]?.trim() && !cols[3]?.trim()) || (!cols[2]?.trim() && cols[3]?.trim())));
+        });
+    }
+    if (hasHeader) {
+        const { dateColumn, amountColumn, descriptionColumn, debitColumn, creditColumn } = analyzeHeaders(firstLine);
+        const safe = (v) => (v && v.trim() ? v : undefined);
+        if (hasDebitCredit && debitColumn && creditColumn) {
+            const dateCol = safe(dateColumn ?? undefined) ?? safe(firstLine[0]);
+            if (!dateCol)
+                throw new Error('Unable to detect date column name from header');
+            const descCol = safe(descriptionColumn ?? undefined) ?? safe(firstLine[1]);
+            if (!descCol)
+                throw new Error('Unable to detect description column name from header');
+            return {
+                date_column: dateCol,
+                description_column: descCol,
+                debit_column: debitColumn,
+                credit_column: creditColumn,
+                date_format: detectDateFormat(linesRaw[1]?.split(delimiter)[0]),
+                has_header: hasHeader,
+                delimiter: delimiter,
+            };
+        }
+        else {
+            const dateCol = safe(dateColumn ?? undefined) ?? safe(firstLine[0]);
+            if (!dateCol)
+                throw new Error('Unable to detect date column name from header');
+            const amountCol = safe(amountColumn ?? undefined) ?? safe(firstLine[1]);
+            if (!amountCol)
+                throw new Error('Unable to detect amount column name from header');
+            const descCol = safe(descriptionColumn ?? undefined) ??
+                safe(firstLine.length >= 3 ? firstLine[2] : firstLine[1]);
+            if (!descCol)
+                throw new Error('Unable to detect description column name from header');
+            return {
+                date_column: dateCol,
+                amount_column: amountCol,
+                description_column: descCol,
+                date_format: detectDateFormat(linesRaw[1]?.split(delimiter)[0]),
+                has_header: hasHeader,
+                delimiter: delimiter,
+            };
+        }
+    }
+    else {
+        if (hasDebitCredit && firstLine.length >= 4) {
+            return {
+                date_column: 0,
+                description_column: 1,
+                debit_column: 2,
+                credit_column: 3,
+                date_format: detectDateFormat(firstLine[0]),
+                has_header: hasHeader,
+                delimiter: delimiter,
+            };
+        }
+        else {
+            return {
+                date_column: 0,
+                amount_column: 1,
+                description_column: firstLine.length >= 3 ? 2 : 1,
+                date_format: detectDateFormat(firstLine[0]),
+                has_header: hasHeader,
+                delimiter: delimiter,
+            };
+        }
+    }
+}
+function preprocessCSV(csvContent, format) {
+    if (format.date_format?.includes('MMM') && format.date_format?.includes(',')) {
+        const lines = csvContent.split('\n');
+        const fixedLines = lines.map((line, index) => {
+            if (format.has_header && index === 0)
+                return line;
+            if (!line.trim())
+                return line;
+            const parts = line.split(format.delimiter);
+            const expectedColumns = format.has_header ? lines[0]?.split(format.delimiter).length || 3 : 3;
+            if (parts.length > expectedColumns) {
+                const potentialDate = parts.slice(0, 2).join(',');
+                if (/^[A-Za-z]{3}\s+\d{1,2},\s+\d{4}/.test(potentialDate)) {
+                    const dateField = parts.slice(0, 2).join(',');
+                    const remainingFields = parts.slice(2);
+                    return `"${dateField}"${format.delimiter}${remainingFields.join(format.delimiter)}`;
+                }
+            }
+            return line;
+        });
+        return fixedLines.join('\n');
+    }
+    return csvContent;
+}
+export function parseBankCSV(csvContent, format, options = {}) {
+    const processedCSV = preprocessCSV(csvContent, format);
+    const records = parse(processedCSV, {
+        delimiter: format.delimiter,
+        columns: format.has_header,
+        skip_empty_lines: true,
+        trim: true,
+        quote: '"',
+        escape: '"',
+        relax_column_count: true,
+    });
+    const transactions = [];
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        const rowNumber = format.has_header ? i + 2 : i + 1;
+        try {
+            let rawDate;
+            let rawAmount;
+            let description;
+            if (format.has_header) {
+                const recordObj = record;
+                rawDate = recordObj[format.date_column] || '';
+                if (format.amount_column) {
+                    rawAmount = recordObj[format.amount_column] || '';
+                }
+                else if (format.debit_column !== undefined && format.credit_column !== undefined) {
+                    const debitVal = recordObj[format.debit_column] || '';
+                    const creditVal = recordObj[format.credit_column] || '';
+                    const debitNum = parseFloat(debitVal.replace(/[^\d.-]/g, ''));
+                    const creditNum = parseFloat(creditVal.replace(/[^\d.-]/g, ''));
+                    if (!isNaN(debitNum) && debitNum !== 0) {
+                        rawAmount = `-${debitVal}`;
+                    }
+                    else if (!isNaN(creditNum) && creditNum !== 0) {
+                        rawAmount = creditVal;
+                    }
+                    else {
+                        rawAmount = '0';
+                    }
+                }
+                else {
+                    throw new Error('No amount column configuration found');
+                }
+                description = recordObj[format.description_column] || '';
+            }
+            else {
+                const recordArray = record;
+                const dateIndex = typeof format.date_column === 'number'
+                    ? format.date_column
+                    : parseInt(format.date_column, 10);
+                const descIndex = typeof format.description_column === 'number'
+                    ? format.description_column
+                    : parseInt(format.description_column, 10);
+                const safeDateIndex = isNaN(dateIndex) ? 0 : dateIndex;
+                const safeDescIndex = isNaN(descIndex) ? 2 : descIndex;
+                rawDate = recordArray[safeDateIndex] || '';
+                if (format.amount_column !== undefined) {
+                    const amountIndex = typeof format.amount_column === 'number'
+                        ? format.amount_column
+                        : parseInt(format.amount_column, 10);
+                    const safeAmountIndex = isNaN(amountIndex) ? 1 : amountIndex;
+                    rawAmount = recordArray[safeAmountIndex] || '';
+                }
+                else if (format.debit_column !== undefined && format.credit_column !== undefined) {
+                    const debitIndex = typeof format.debit_column === 'number'
+                        ? format.debit_column
+                        : parseInt(format.debit_column, 10);
+                    const creditIndex = typeof format.credit_column === 'number'
+                        ? format.credit_column
+                        : parseInt(format.credit_column, 10);
+                    const debitVal = recordArray[debitIndex] || '';
+                    const creditVal = recordArray[creditIndex] || '';
+                    const debitNum = parseFloat(debitVal.replace(/[^\d.-]/g, ''));
+                    const creditNum = parseFloat(creditVal.replace(/[^\d.-]/g, ''));
+                    if (!isNaN(debitNum) && debitNum !== 0) {
+                        rawAmount = `-${debitVal}`;
+                    }
+                    else if (!isNaN(creditNum) && creditNum !== 0) {
+                        rawAmount = creditVal;
+                    }
+                    else {
+                        rawAmount = '0';
+                    }
+                }
+                else {
+                    throw new Error('No amount column configuration found');
+                }
+                description = recordArray[safeDescIndex] || '';
+            }
+            if (!rawDate || !rawAmount) {
+                if (options.debug) {
+                    console.warn(`Skipping row ${rowNumber}: missing date or amount`);
+                }
+                continue;
+            }
+            const date = parseDate(rawDate, format.date_format);
+            let amount;
+            try {
+                amount = amountToMilliunits(rawAmount);
+            }
+            catch (error) {
+                if (options.debug) {
+                    console.warn(`Skipping row ${rowNumber}: ${error instanceof Error ? error.message : 'Invalid amount'}`);
+                }
+                continue;
+            }
+            transactions.push({
+                date,
+                amount,
+                description: description.trim(),
+                raw_amount: rawAmount,
+                raw_date: rawDate,
+                row_number: rowNumber,
+            });
+        }
+        catch (error) {
+            if (options.debug) {
+                console.warn(`Error parsing row ${rowNumber}:`, error);
+            }
+            continue;
+        }
+    }
+    return transactions;
+}
+export function readCSVFile(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Unable to read CSV file: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+export function extractDateRangeFromCSV(csvContent, format) {
+    const transactions = parseBankCSV(csvContent, format);
+    if (transactions.length === 0) {
+        throw new Error('No transactions found in CSV');
+    }
+    const dates = transactions.map((txn) => txn.date.getTime());
+    const minDateObj = new Date(Math.min(...dates));
+    const maxDateObj = new Date(Math.max(...dates));
+    const toYYYYMMDD = (date) => {
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        return `${year}-${month}-${day}`;
+    };
+    return {
+        minDate: toYYYYMMDD(minDateObj),
+        maxDate: toYYYYMMDD(maxDateObj),
+    };
+}

package/dist/tools/compareTransactions/types.d.ts

@@ -0,0 +1,27 @@
+import type * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import type { CompareTransactionsSchema } from './index.js';
+export interface BankTransaction {
+    date: Date;
+    amount: number;
+    description: string;
+    raw_amount: string;
+    raw_date: string;
+    row_number: number;
+}
+export interface YNABTransaction {
+    id: string;
+    date: Date;
+    amount: number;
+    payee_name: string | null | undefined;
+    memo: string | null | undefined;
+    cleared: string;
+    original: ynab.TransactionDetail;
+}
+export interface TransactionMatch {
+    bank_transaction: BankTransaction;
+    ynab_transaction: YNABTransaction;
+    match_score: number;
+    match_reasons: string[];
+}
+export type CSVFormat = z.infer<typeof CompareTransactionsSchema>['csv_format'];

package/dist/tools/compareTransactions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/compareTransactions.d.ts

@@ -0,0 +1 @@
+export * from './compareTransactions/index.js';

package/dist/tools/compareTransactions.js

@@ -0,0 +1 @@
+export * from './compareTransactions/index.js';

package/dist/tools/deltaFetcher.d.ts

@@ -0,0 +1,22 @@
+import * as ynab from 'ynab';
+import { DeltaCache, type DeltaFetchResult } from '../server/deltaCache.js';
+export interface DeltaFetchOptions {
+    forceFullRefresh?: boolean;
+    ttl?: number;
+}
+export declare class DeltaFetcher {
+    private readonly ynabAPI;
+    private readonly deltaCache;
+    constructor(ynabAPI: ynab.API, deltaCache: DeltaCache);
+    fetchAccounts(budgetId: string, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.Account>>;
+    fetchCategories(budgetId: string, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.CategoryGroupWithCategories>>;
+    fetchTransactions(budgetId: string, sinceDate?: string, type?: ynab.GetTransactionsTypeEnum, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.TransactionDetail>>;
+    fetchTransactionsByAccount(budgetId: string, accountId: string, sinceDate?: string, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.TransactionDetail>>;
+    fetchAccountsFull(budgetId: string): Promise<DeltaFetchResult<ynab.Account>>;
+    fetchTransactionsByAccountFull(budgetId: string, accountId: string, sinceDate?: string): Promise<DeltaFetchResult<ynab.TransactionDetail>>;
+    fetchScheduledTransactions(budgetId: string, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.ScheduledTransactionDetail>>;
+    fetchPayees(budgetId: string, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.Payee>>;
+    fetchMonths(budgetId: string, options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.MonthSummary>>;
+    fetchBudgets(options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.BudgetSummary>>;
+    private buildDeltaOptions;
+}

package/dist/tools/deltaFetcher.js

@@ -0,0 +1,137 @@
+import { mergeFlatEntities, mergeCategories, mergeTransactions, mergeMonths, } from '../server/deltaCache.merge.js';
+import { CacheManager, CACHE_TTLS } from '../server/cacheManager.js';
+export class DeltaFetcher {
+    constructor(ynabAPI, deltaCache) {
+        this.ynabAPI = ynabAPI;
+        this.deltaCache = deltaCache;
+    }
+    async fetchAccounts(budgetId, options) {
+        const cacheKey = CacheManager.generateKey('accounts', 'list', budgetId);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = lastKnowledge !== undefined
+                ? await this.ynabAPI.accounts.getAccounts(budgetId, lastKnowledge)
+                : await this.ynabAPI.accounts.getAccounts(budgetId);
+            return {
+                data: response.data.accounts,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeFlatEntities, this.buildDeltaOptions(CACHE_TTLS.ACCOUNTS, options));
+    }
+    async fetchCategories(budgetId, options) {
+        const cacheKey = CacheManager.generateKey('categories', 'list', budgetId);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = lastKnowledge !== undefined
+                ? await this.ynabAPI.categories.getCategories(budgetId, lastKnowledge)
+                : await this.ynabAPI.categories.getCategories(budgetId);
+            return {
+                data: response.data.category_groups,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeCategories, this.buildDeltaOptions(CACHE_TTLS.CATEGORIES, options));
+    }
+    async fetchTransactions(budgetId, sinceDate, type, options) {
+        const normalizedSince = sinceDate ?? 'all';
+        const normalizedType = type ?? 'all';
+        const cacheKey = CacheManager.generateKey('transactions', 'list', budgetId, normalizedSince, normalizedType);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = await this.ynabAPI.transactions.getTransactions(budgetId, sinceDate, type, lastKnowledge);
+            return {
+                data: response.data.transactions,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeTransactions, this.buildDeltaOptions(CACHE_TTLS.TRANSACTIONS, options));
+    }
+    async fetchTransactionsByAccount(budgetId, accountId, sinceDate, options) {
+        const normalizedSince = sinceDate ?? 'all';
+        const cacheKey = CacheManager.generateKey('transactions', 'account', budgetId, accountId, normalizedSince);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = await this.ynabAPI.transactions.getTransactionsByAccount(budgetId, accountId, sinceDate, undefined, lastKnowledge);
+            return {
+                data: response.data.transactions,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeTransactions, this.buildDeltaOptions(CACHE_TTLS.TRANSACTIONS, options));
+    }
+    async fetchAccountsFull(budgetId) {
+        const response = await this.ynabAPI.accounts.getAccounts(budgetId);
+        const accounts = response.data.accounts.filter((account) => !account.deleted);
+        return {
+            data: accounts,
+            wasCached: false,
+            usedDelta: false,
+            serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+    }
+    async fetchTransactionsByAccountFull(budgetId, accountId, sinceDate) {
+        const response = await this.ynabAPI.transactions.getTransactionsByAccount(budgetId, accountId, sinceDate);
+        const transactions = response.data.transactions.filter((transaction) => !transaction.deleted);
+        return {
+            data: transactions,
+            wasCached: false,
+            usedDelta: false,
+            serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+    }
+    async fetchScheduledTransactions(budgetId, options) {
+        const cacheKey = CacheManager.generateKey('scheduled_transactions', 'list', budgetId);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = lastKnowledge !== undefined
+                ? await this.ynabAPI.scheduledTransactions.getScheduledTransactions(budgetId, lastKnowledge)
+                : await this.ynabAPI.scheduledTransactions.getScheduledTransactions(budgetId);
+            return {
+                data: response.data.scheduled_transactions,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeFlatEntities, this.buildDeltaOptions(CACHE_TTLS.SCHEDULED_TRANSACTIONS, options));
+    }
+    async fetchPayees(budgetId, options) {
+        const cacheKey = CacheManager.generateKey('payees', 'list', budgetId);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = lastKnowledge !== undefined
+                ? await this.ynabAPI.payees.getPayees(budgetId, lastKnowledge)
+                : await this.ynabAPI.payees.getPayees(budgetId);
+            return {
+                data: response.data.payees,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeFlatEntities, this.buildDeltaOptions(CACHE_TTLS.PAYEES, options));
+    }
+    async fetchMonths(budgetId, options) {
+        const cacheKey = CacheManager.generateKey('months', 'list', budgetId);
+        return await this.deltaCache.fetchWithDelta(cacheKey, budgetId, async (lastKnowledge) => {
+            const response = lastKnowledge !== undefined
+                ? await this.ynabAPI.months.getBudgetMonths(budgetId, lastKnowledge)
+                : await this.ynabAPI.months.getBudgetMonths(budgetId);
+            return {
+                data: response.data.months,
+                serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+        }, mergeMonths, this.buildDeltaOptions(CACHE_TTLS.MONTHS, options));
+    }
+    async fetchBudgets(options) {
+        const cacheKey = CacheManager.generateKey('budgets', 'list');
+        const result = await this.deltaCache.fetchWithDelta(cacheKey, 'global', async () => {
+            const response = await this.ynabAPI.budgets.getBudgets();
+            const serverKnowledge = response.data.server_knowledge ?? 0;
+            return {
+                data: response.data.budgets,
+                serverKnowledge,
+            };
+        }, mergeFlatEntities, {
+            ttl: options?.ttl ?? CACHE_TTLS.BUDGETS,
+            forceFullRefresh: true,
+        });
+        return {
+            ...result,
+            data: result.data,
+        };
+    }
+    buildDeltaOptions(defaultTtl, options) {
+        return {
+            ttl: options?.ttl ?? defaultTtl,
+            ...(options?.forceFullRefresh !== undefined && {
+                forceFullRefresh: options.forceFullRefresh,
+            }),
+        };
+    }
+}

package/dist/tools/deltaSupport.d.ts

@@ -0,0 +1,20 @@
+import * as ynab from 'ynab';
+import { DeltaCache } from '../server/deltaCache.js';
+import { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import { DeltaFetcher } from './deltaFetcher.js';
+export interface SharedDeltaSupportOptions {
+    deltaFetcher?: DeltaFetcher;
+    deltaCache?: DeltaCache;
+    knowledgeStore?: ServerKnowledgeStore;
+}
+export declare function setSharedDeltaSupport(options?: SharedDeltaSupportOptions): void;
+export declare function getSharedDeltaSupport(): SharedDeltaSupportOptions | undefined;
+export declare function resolveDeltaFetcherArgs<TParams extends Record<string, unknown>>(ynabAPI: ynab.API, deltaFetcherOrParams: DeltaFetcher | TParams, maybeParams?: TParams): {
+    deltaFetcher: DeltaFetcher;
+    params: TParams;
+};
+export declare function resolveDeltaWriteArgs<TParams extends Record<string, unknown>>(deltaCacheOrParams: DeltaCache | TParams, knowledgeStoreOrParams?: ServerKnowledgeStore | TParams, maybeParams?: TParams): {
+    deltaCache: DeltaCache;
+    knowledgeStore: ServerKnowledgeStore;
+    params: TParams;
+};