ynab-mcp-deluxe 0.1.9

package/dist/ynab-client.js

@@ -0,0 +1,1248 @@
+/**
+ * YNAB API client wrapper with caching and enrichment
+ */
+import { api as YnabApi, TransactionClearedStatus, utils, } from 'ynab';
+import { checkForDrift, isAlwaysFullSyncEnabled, isDriftDetectionEnabled, logDriftCheckResult, recordDriftCheck, shouldPerformDriftCheck, } from './drift-detection.js';
+import { saveDriftSnapshot, shouldSampleDrift } from './drift-snapshot.js';
+import { buildLocalBudget, mergeDelta } from './local-budget.js';
+import { createCombinedLogger, fileLogger } from './logger.js';
+import { persistSyncResponse } from './sync-history.js';
+import { ApiSyncProvider } from './sync-providers.js';
+// ============================================================================
+// Read-Only Mode Support
+// ============================================================================
+/**
+ * Check if the server is running in read-only mode
+ */
+export function isReadOnlyMode() {
+    const value = process.env['YNAB_READ_ONLY'];
+    return value === 'true' || value === '1';
+}
+/**
+ * Assert that write operations are allowed
+ * @throws Error if read-only mode is enabled
+ */
+export function assertWriteAllowed(operation) {
+    if (isReadOnlyMode()) {
+        throw new Error(`Write operation "${operation}" blocked: Server is in read-only mode. ` +
+            `Set YNAB_READ_ONLY=false to enable writes.`);
+    }
+}
+// ============================================================================
+// Sync Configuration
+// ============================================================================
+// Enrichment Helpers
+// ============================================================================
+//
+// These helpers handle name resolution for transactions and subtransactions.
+//
+// Why we check for existing names (not dead code):
+// - The YNAB SDK types for SubTransaction and ScheduledSubTransaction include
+//   optional payee_name and category_name fields
+// - The FULL BUDGET endpoint (/budgets/{id}) returns TransactionSummary which
+//   may NOT populate these fields (only IDs are guaranteed)
+// - INDIVIDUAL transaction endpoints DO populate these name fields
+// - We defensively check for existing names first, then fall back to ID lookup
+//   This ensures we work correctly regardless of which endpoint provided the data
+// ============================================================================
+/**
+ * Resolve a payee name from a payee ID using the LocalBudget lookup maps.
+ * Returns the existing name if already provided, otherwise looks up by ID.
+ *
+ * @param payeeId - The payee ID to look up
+ * @param existingName - Pre-populated name (may be present from individual tx endpoints)
+ * @param localBudget - LocalBudget with payee lookup maps
+ */
+function resolvePayeeName(payeeId, existingName, localBudget) {
+    if (existingName !== undefined &&
+        existingName !== null &&
+        existingName !== '')
+        return existingName;
+    if (payeeId === undefined || payeeId === null)
+        return null;
+    return localBudget.payeeById.get(payeeId)?.name ?? null;
+}
+/**
+ * Resolve category name and category group name from a category ID.
+ * Returns the existing names if already provided, otherwise looks up by ID.
+ *
+ * @param categoryId - The category ID to look up
+ * @param existingName - Pre-populated name (may be present from individual tx endpoints)
+ * @param localBudget - LocalBudget with category lookup maps
+ */
+function resolveCategoryInfo(categoryId, existingName, localBudget) {
+    if (existingName !== undefined &&
+        existingName !== null &&
+        existingName !== '') {
+        // We have the name but still need the group name from lookup
+        const category = categoryId !== undefined && categoryId !== null
+            ? localBudget.categoryById.get(categoryId)
+            : undefined;
+        const categoryGroupName = category !== undefined
+            ? (localBudget.categoryGroupNameById.get(category.category_group_id) ??
+                null)
+            : null;
+        return { categoryGroupName, categoryName: existingName };
+    }
+    if (categoryId === undefined || categoryId === null) {
+        return { categoryGroupName: null, categoryName: null };
+    }
+    const category = localBudget.categoryById.get(categoryId);
+    if (category === undefined) {
+        return { categoryGroupName: null, categoryName: null };
+    }
+    const categoryGroupName = localBudget.categoryGroupNameById.get(category.category_group_id) ?? null;
+    return { categoryGroupName, categoryName: category.name };
+}
+// ============================================================================
+/**
+ * Default sync interval in seconds (10 minutes)
+ */
+const DEFAULT_SYNC_INTERVAL_SECONDS = 600;
+/**
+ * Get the configured sync interval in milliseconds.
+ * Configured via YNAB_SYNC_INTERVAL_SECONDS environment variable.
+ * Default: 600 seconds (10 minutes)
+ * Set to 0 to always sync before every operation.
+ */
+export function getSyncIntervalMs() {
+    const value = process.env['YNAB_SYNC_INTERVAL_SECONDS'];
+    if (value === undefined || value === '') {
+        return DEFAULT_SYNC_INTERVAL_SECONDS * 1000;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed < 0) {
+        // Invalid value, use default
+        return DEFAULT_SYNC_INTERVAL_SECONDS * 1000;
+    }
+    return parsed * 1000;
+}
+function analyzeEntityArray(items) {
+    if (items === undefined || items.length === 0) {
+        return { count: 0, deletedCount: 0, sampleIds: [] };
+    }
+    const deletedCount = items.filter((item) => item.deleted === true).length;
+    const sampleIds = items.slice(0, 3).map((item) => item.id);
+    return {
+        count: items.length,
+        deletedCount,
+        sampleIds,
+    };
+}
+function analyzeDeltaResponse(deltaBudget) {
+    // Helper for months which use 'month' instead of 'id'
+    const analyzeMonths = (items) => {
+        if (items === undefined || items.length === 0) {
+            return { count: 0, deletedCount: 0, sampleIds: [] };
+        }
+        const deletedCount = items.filter((item) => item.deleted === true).length;
+        const sampleIds = items.slice(0, 3).map((item) => item.month);
+        return { count: items.length, deletedCount, sampleIds };
+    };
+    return {
+        accounts: analyzeEntityArray(deltaBudget.accounts),
+        categories: analyzeEntityArray(deltaBudget.categories),
+        months: analyzeMonths(deltaBudget.months),
+        payees: analyzeEntityArray(deltaBudget.payees),
+        scheduledTransactions: analyzeEntityArray(deltaBudget.scheduled_transactions),
+        transactions: analyzeEntityArray(deltaBudget.transactions),
+    };
+}
+/**
+ * Default logger when no context is available - logs to file only.
+ */
+const defaultLog = fileLogger;
+/**
+ * YNAB client with local budget sync
+ */
+class YnabClient {
+    api = null;
+    budgets = null;
+    localBudgets = new Map();
+    /** Store previous full API responses for drift snapshot collection */
+    previousBudgetDetails = new Map();
+    lastUsedBudgetId = null;
+    syncProvider = null;
+    /**
+     * Get the YNAB API instance, creating it if necessary
+     */
+    getApi() {
+        if (this.api === null) {
+            const token = process.env['YNAB_ACCESS_TOKEN'];
+            if (token === undefined || token === '') {
+                throw new Error('YNAB authentication failed. Check that YNAB_ACCESS_TOKEN environment variable is set.');
+            }
+            this.api = new YnabApi(token);
+        }
+        return this.api;
+    }
+    /**
+     * Get the sync provider, creating it if necessary
+     */
+    getSyncProvider() {
+        if (this.syncProvider === null) {
+            const token = process.env['YNAB_ACCESS_TOKEN'];
+            if (token === undefined || token === '') {
+                throw new Error('YNAB authentication failed. Check that YNAB_ACCESS_TOKEN environment variable is set.');
+            }
+            this.syncProvider = new ApiSyncProvider(token);
+        }
+        return this.syncProvider;
+    }
+    /**
+     * Determine what kind of sync is needed based on policy.
+     * Returns both the sync type and the reason for logging.
+     */
+    determineSyncNeeded(localBudget, options) {
+        // Force full sync requested
+        if (options.forceSync === 'full') {
+            return { reason: 'forceSync: full requested', type: 'full' };
+        }
+        // No local budget yet - need initial full sync
+        if (localBudget === undefined) {
+            return { reason: 'no local budget exists (initial sync)', type: 'full' };
+        }
+        // "Always full sync" mode - skip delta optimization entirely
+        // This is a valid production strategy if delta sync proves unreliable
+        if (isAlwaysFullSyncEnabled()) {
+            return { reason: 'YNAB_ALWAYS_FULL_SYNC enabled', type: 'full' };
+        }
+        // Force delta sync requested
+        if (options.forceSync === 'delta') {
+            return { reason: 'forceSync: delta requested', type: 'delta' };
+        }
+        // Write happened - need to sync
+        if (localBudget.needsSync) {
+            return {
+                reason: 'needsSync flag set (write operation occurred)',
+                type: 'delta',
+            };
+        }
+        // Check interval
+        const elapsed = Date.now() - localBudget.lastSyncedAt.getTime();
+        const intervalMs = getSyncIntervalMs();
+        if (elapsed >= intervalMs) {
+            const elapsedSeconds = Math.round(elapsed / 1000);
+            const intervalSeconds = Math.round(intervalMs / 1000);
+            return {
+                reason: `sync interval passed (${elapsedSeconds}s elapsed, interval: ${intervalSeconds}s)`,
+                type: 'delta',
+            };
+        }
+        // Local budget is fresh enough
+        const remainingMs = intervalMs - elapsed;
+        const remainingSeconds = Math.round(remainingMs / 1000);
+        return {
+            reason: `local budget is fresh (${remainingSeconds}s until next sync)`,
+            type: 'none',
+        };
+    }
+    /**
+     * Get a local budget, syncing with YNAB if needed.
+     *
+     * SYNC STRATEGY (Drift Collection Mode):
+     * - Always fetch full budget (guaranteed correct)
+     * - Also fetch delta and merge to build "merged" version for comparison
+     * - Run drift detection comparing merged vs full
+     * - If drift detected (at sample rate), save artifacts for later analysis
+     * - Return the full budget (source of truth)
+     *
+     * This approach unblocks development while passively collecting drift data.
+     *
+     * @param budgetId - The budget ID
+     * @param options - Sync options (forceSync: 'full' | 'delta' | undefined)
+     * @param log - Logger for debug output
+     * @returns The LocalBudget
+     */
+    async getLocalBudgetWithSync(budgetId, options = {}, contextLog = defaultLog) {
+        // Create combined logger that writes to both file and context
+        const log = createCombinedLogger(contextLog);
+        const existingBudget = this.localBudgets.get(budgetId);
+        const previousBudgetDetail = this.previousBudgetDetails.get(budgetId);
+        const syncDecision = this.determineSyncNeeded(existingBudget, options);
+        log.debug('Sync decision', {
+            budgetId,
+            decision: syncDecision.type,
+            hasPreviousBudget: existingBudget !== undefined,
+            reason: syncDecision.reason,
+        });
+        if (syncDecision.type === 'none' && existingBudget !== undefined) {
+            log.debug('Local budget is fresh, skipping sync', {
+                budgetId,
+                lastSyncedAt: existingBudget.lastSyncedAt.toISOString(),
+                serverKnowledge: existingBudget.serverKnowledge,
+            });
+            return existingBudget;
+        }
+        const syncProvider = this.getSyncProvider();
+        const totalStartTime = performance.now();
+        // If we have an existing budget, try delta sync first for drift collection
+        let mergedBudget = null;
+        let deltaBudgetData = null;
+        let deltaServerKnowledge = null;
+        if (existingBudget !== undefined &&
+            previousBudgetDetail !== undefined &&
+            isDriftDetectionEnabled() &&
+            shouldPerformDriftCheck(budgetId)) {
+            // Fetch delta and merge for drift comparison
+            const previousServerKnowledge = existingBudget.serverKnowledge;
+            log.info('Fetching delta for drift collection...', {
+                budgetId,
+                previousServerKnowledge,
+            });
+            try {
+                const deltaStartTime = performance.now();
+                const deltaResult = await syncProvider.deltaSync(budgetId, previousServerKnowledge);
+                deltaBudgetData = deltaResult.budget;
+                deltaServerKnowledge = deltaResult.serverKnowledge;
+                const deltaDurationMs = Math.round(performance.now() - deltaStartTime);
+                // Analyze delta for logging
+                const deltaAnalysis = analyzeDeltaResponse(deltaBudgetData);
+                const knowledgeChanged = deltaServerKnowledge !== previousServerKnowledge;
+                log.debug('Delta response for drift collection', {
+                    deltaAnalysis,
+                    deltaDurationMs,
+                    knowledgeChanged,
+                    serverKnowledge: {
+                        new: deltaServerKnowledge,
+                        previous: previousServerKnowledge,
+                    },
+                });
+                // Merge delta into existing budget
+                const mergeStartTime = performance.now();
+                const mergeResult = mergeDelta(existingBudget, deltaBudgetData, deltaServerKnowledge);
+                mergedBudget = mergeResult.localBudget;
+                const mergeDurationMs = Math.round(performance.now() - mergeStartTime);
+                log.debug('Delta merged for drift comparison', {
+                    changesReceived: mergeResult.changesReceived,
+                    mergeDurationMs,
+                });
+            }
+            catch (error) {
+                log.warn('Delta fetch failed for drift collection, continuing', {
+                    budgetId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // Always fetch full budget (source of truth)
+        log.info('Performing full sync...', {
+            budgetId,
+            reason: syncDecision.reason,
+        });
+        const apiStartTime = performance.now();
+        const { budget: fullBudgetData, serverKnowledge: fullServerKnowledge } = await syncProvider.fullSync(budgetId);
+        const apiDurationMs = Math.round(performance.now() - apiStartTime);
+        const buildStartTime = performance.now();
+        const localBudget = buildLocalBudget(budgetId, fullBudgetData, fullServerKnowledge);
+        const buildDurationMs = Math.round(performance.now() - buildStartTime);
+        // Persist to sync history
+        const persistStartTime = performance.now();
+        await persistSyncResponse(budgetId, 'full', fullBudgetData, fullServerKnowledge, null, log);
+        const persistDurationMs = Math.round(performance.now() - persistStartTime);
+        const totalDurationMs = Math.round(performance.now() - totalStartTime);
+        log.info('Full sync completed', {
+            apiDurationMs,
+            budgetId,
+            buildDurationMs,
+            counts: {
+                accounts: localBudget.accounts.length,
+                categories: localBudget.categories.length,
+                payees: localBudget.payees.length,
+                transactions: localBudget.transactions.length,
+            },
+            persistDurationMs,
+            serverKnowledge: fullServerKnowledge,
+            totalDurationMs,
+        });
+        // Run drift detection if we have a merged budget to compare
+        if (mergedBudget !== null &&
+            deltaBudgetData !== null &&
+            deltaServerKnowledge !== null &&
+            previousBudgetDetail !== undefined) {
+            log.info('Running drift detection...', { budgetId });
+            const compareStartTime = performance.now();
+            const driftResult = checkForDrift(mergedBudget, localBudget);
+            const compareDurationMs = Math.round(performance.now() - compareStartTime);
+            logDriftCheckResult(driftResult, budgetId, log);
+            recordDriftCheck(budgetId);
+            log.debug('Drift check timing', { compareDurationMs });
+            // Save snapshot if drift detected and we're sampling
+            if (driftResult.hasDrift && shouldSampleDrift()) {
+                try {
+                    await saveDriftSnapshot({
+                        budgetId,
+                        deltaResponse: deltaBudgetData,
+                        driftResult,
+                        fullResponse: fullBudgetData,
+                        mergedBudget,
+                        previousFullResponse: previousBudgetDetail,
+                        serverKnowledge: {
+                            afterDelta: deltaServerKnowledge,
+                            afterFull: fullServerKnowledge,
+                            previous: existingBudget?.serverKnowledge ?? 0,
+                        },
+                    }, log);
+                }
+                catch (error) {
+                    log.warn('Failed to save drift snapshot, continuing', {
+                        budgetId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        // Store the full budget and response for next time
+        this.localBudgets.set(budgetId, localBudget);
+        this.previousBudgetDetails.set(budgetId, fullBudgetData);
+        return localBudget;
+    }
+    /**
+     * Mark a budget as needing sync (called after write operations).
+     * The next read operation will trigger a delta sync.
+     */
+    markNeedsSync(budgetId) {
+        const localBudget = this.localBudgets.get(budgetId);
+        if (localBudget !== undefined) {
+            localBudget.needsSync = true;
+        }
+    }
+    /**
+     * Get all budgets
+     */
+    async getBudgets() {
+        if (this.budgets === null) {
+            const response = await this.getApi().budgets.getBudgets();
+            this.budgets = response.data.budgets;
+        }
+        return this.budgets.map((b) => ({
+            currency_format: b.currency_format !== undefined && b.currency_format !== null
+                ? {
+                    currency_symbol: b.currency_format.currency_symbol,
+                    decimal_digits: b.currency_format.decimal_digits,
+                    decimal_separator: b.currency_format.decimal_separator,
+                    example_format: b.currency_format.example_format,
+                    iso_code: b.currency_format.iso_code,
+                    symbol_first: b.currency_format.symbol_first,
+                }
+                : null,
+            first_month: b.first_month ?? null,
+            id: b.id,
+            last_modified_on: b.last_modified_on ?? null,
+            last_month: b.last_month ?? null,
+            name: b.name,
+        }));
+    }
+    /**
+     * Resolve a budget selector to a budget ID
+     *
+     * IMPORTANT: If YNAB_BUDGET_ID is set, it acts as a HARD CONSTRAINT.
+     * Only that budget can be accessed - any attempt to use a different
+     * budget will throw an error. This is a safety mechanism for testing.
+     */
+    async resolveBudgetId(selector) {
+        const budgets = await this.getBudgets();
+        const hasName = selector?.name !== undefined && selector.name !== '';
+        const hasId = selector?.id !== undefined && selector.id !== '';
+        // Check for YNAB_BUDGET_ID environment variable - this is a HARD CONSTRAINT
+        const envBudgetId = process.env['YNAB_BUDGET_ID'];
+        const hasEnvConstraint = envBudgetId !== undefined && envBudgetId !== '';
+        if (hasEnvConstraint) {
+            // Verify the constrained budget exists
+            const constrainedBudget = budgets.find((b) => b.id === envBudgetId);
+            if (constrainedBudget === undefined) {
+                throw new Error(`YNAB_BUDGET_ID is set to '${envBudgetId}' but no budget with that ID exists. ` +
+                    `Available budgets: ${budgets.map((b) => `${b.name} (${b.id})`).join(', ')}.`);
+            }
+            // If no selector provided, use the constrained budget
+            if (selector === undefined || (!hasName && !hasId)) {
+                this.lastUsedBudgetId = constrainedBudget.id;
+                return constrainedBudget.id;
+            }
+            // Validate selector format
+            if (hasName && hasId) {
+                throw new Error("Budget selector must specify exactly one of: 'name' or 'id'.");
+            }
+            // If selector specifies an ID, it MUST match the constrained ID
+            if (hasId) {
+                if (selector.id !== envBudgetId) {
+                    throw new Error(`Budget access denied. YNAB_BUDGET_ID restricts access to budget '${constrainedBudget.name}' (${envBudgetId}). ` +
+                        `Attempted to access budget with ID: '${selector.id}'.`);
+                }
+                this.lastUsedBudgetId = constrainedBudget.id;
+                return constrainedBudget.id;
+            }
+            // If selector specifies a name, resolve it and verify it matches
+            const nameLower = (selector.name ?? '').toLowerCase();
+            const namedBudget = budgets.find((b) => b.name.toLowerCase() === nameLower);
+            if (namedBudget === undefined) {
+                throw new Error(`No budget found with name: '${selector.name}'. ` +
+                    `Note: YNAB_BUDGET_ID restricts access to '${constrainedBudget.name}'.`);
+            }
+            if (namedBudget.id !== envBudgetId) {
+                throw new Error(`Budget access denied. YNAB_BUDGET_ID restricts access to budget '${constrainedBudget.name}' (${envBudgetId}). ` +
+                    `Attempted to access budget '${namedBudget.name}' (${namedBudget.id}).`);
+            }
+            this.lastUsedBudgetId = constrainedBudget.id;
+            return constrainedBudget.id;
+        }
+        // No env constraint - use normal resolution logic
+        // If no selector provided, use last-used or single budget
+        if (selector === undefined || (!hasName && !hasId)) {
+            if (this.lastUsedBudgetId !== null) {
+                return this.lastUsedBudgetId;
+            }
+            const firstBudget = budgets[0];
+            if (budgets.length === 1 && firstBudget !== undefined) {
+                this.lastUsedBudgetId = firstBudget.id;
+                return firstBudget.id;
+            }
+            const budgetNames = budgets.map((b) => b.name).join(', ');
+            throw new Error(`Multiple budgets found. Please specify which budget using {"name": "..."} or {"id": "..."}. Available: ${budgetNames}.`);
+        }
+        // Validate selector has exactly one of name or id
+        if (hasName && hasId) {
+            throw new Error("Budget selector must specify exactly one of: 'name' or 'id'.");
+        }
+        // Find by ID
+        if (hasId) {
+            const budget = budgets.find((b) => b.id === selector.id);
+            if (budget === undefined) {
+                const budgetNames = budgets.map((b) => b.name).join(', ');
+                throw new Error(`No budget found with ID: '${selector.id}'. Available budgets: ${budgetNames}.`);
+            }
+            this.lastUsedBudgetId = budget.id;
+            return budget.id;
+        }
+        // Find by name (case-insensitive)
+        // At this point we know hasName is true since hasId was false
+        const nameLower = (selector.name ?? '').toLowerCase();
+        const budget = budgets.find((b) => b.name.toLowerCase() === nameLower);
+        if (budget === undefined) {
+            const budgetNames = budgets.map((b) => b.name).join(', ');
+            throw new Error(`No budget found with name: '${selector.name}'. Available budgets: ${budgetNames}.`);
+        }
+        this.lastUsedBudgetId = budget.id;
+        return budget.id;
+    }
+    /**
+     * Get the local budget for internal use.
+     * This is a convenience wrapper around getLocalBudgetWithSync() for methods
+     * that don't have access to a logger context.
+     */
+    async getLocalBudget(budgetId) {
+        return await this.getLocalBudgetWithSync(budgetId, {}, defaultLog);
+    }
+    /**
+     * Build CategoryGroupWithCategories array from LocalBudget data.
+     * The full budget endpoint returns categories and groups separately,
+     * so we need to join them for compatibility with some existing methods.
+     */
+    buildCategoryGroupsWithCategories(localBudget) {
+        // Group categories by their category_group_id
+        const categoriesByGroupId = new Map();
+        for (const category of localBudget.categories) {
+            const existing = categoriesByGroupId.get(category.category_group_id);
+            if (existing !== undefined) {
+                existing.push(category);
+            }
+            else {
+                categoriesByGroupId.set(category.category_group_id, [category]);
+            }
+        }
+        // Build CategoryGroupWithCategories array
+        return localBudget.categoryGroups.map((group) => ({
+            ...group,
+            categories: categoriesByGroupId.get(group.id) ?? [],
+        }));
+    }
+    /**
+     * Convert milliunits to currency amount
+     */
+    toCurrency(milliunits, currencyFormat) {
+        const decimalDigits = currencyFormat?.decimal_digits ?? 2;
+        return utils.convertMilliUnitsToCurrencyAmount(milliunits, decimalDigits);
+    }
+    /**
+     * Enrich a transaction with resolved names.
+     * Used for TransactionDetail (from individual transaction endpoints),
+     * which already has payee_name, category_name, account_name, and
+     * inline subtransactions[].
+     */
+    enrichTransaction(tx, localBudget) {
+        const { categoryGroupName, categoryName } = resolveCategoryInfo(tx.category_id, tx.category_name, localBudget);
+        // Enrich subtransactions (TransactionDetail has inline subtransactions)
+        const enrichedSubtransactions = tx.subtransactions.map((sub) => {
+            const subCategory = resolveCategoryInfo(sub.category_id, sub.category_name, localBudget);
+            return {
+                amount: sub.amount,
+                amount_currency: this.toCurrency(sub.amount, localBudget.currencyFormat),
+                category_group_name: subCategory.categoryGroupName,
+                category_id: sub.category_id ?? null,
+                category_name: subCategory.categoryName,
+                id: sub.id,
+                memo: sub.memo ?? null,
+                payee_id: sub.payee_id ?? null,
+                payee_name: resolvePayeeName(sub.payee_id, sub.payee_name, localBudget),
+                transaction_id: sub.transaction_id,
+                transfer_account_id: sub.transfer_account_id ?? null,
+            };
+        });
+        return {
+            account_id: tx.account_id,
+            account_name: tx.account_name,
+            amount: tx.amount,
+            amount_currency: this.toCurrency(tx.amount, localBudget.currencyFormat),
+            approved: tx.approved,
+            category_group_name: categoryGroupName,
+            category_id: tx.category_id ?? null,
+            category_name: categoryName,
+            cleared: tx.cleared,
+            date: tx.date,
+            flag_color: tx.flag_color ?? null,
+            id: tx.id,
+            import_id: tx.import_id ?? null,
+            import_payee_name: tx.import_payee_name ?? null,
+            import_payee_name_original: tx.import_payee_name_original ?? null,
+            memo: tx.memo ?? null,
+            payee_id: tx.payee_id ?? null,
+            payee_name: tx.payee_name ?? null,
+            subtransactions: enrichedSubtransactions,
+            transfer_account_id: tx.transfer_account_id ?? null,
+        };
+    }
+    /**
+     * Enrich a TransactionSummary (from full budget endpoint) with resolved names.
+     *
+     * The full budget endpoint returns TransactionSummary[] which only has IDs,
+     * not resolved names. This method looks up names from the LocalBudget's
+     * lookup maps and joins subtransactions from the flat subtransactions array.
+     *
+     * @param tx - The TransactionSummary from LocalBudget.transactions
+     * @param localBudget - The LocalBudget with lookup maps and subtransactions
+     * @returns An EnrichedTransaction with resolved names and subtransactions
+     */
+    enrichTransactionSummary(tx, localBudget) {
+        // Look up account name
+        const account = localBudget.accountById.get(tx.account_id);
+        const accountName = account?.name ?? 'Unknown Account';
+        const payeeName = resolvePayeeName(tx.payee_id, null, localBudget);
+        const { categoryGroupName, categoryName } = resolveCategoryInfo(tx.category_id, null, localBudget);
+        // Get subtransactions for this transaction (O(1) lookup)
+        const subtransactions = (localBudget.subtransactionsByTransactionId.get(tx.id) ?? []).filter((sub) => sub.deleted !== true);
+        // Enrich subtransactions with resolved names
+        const enrichedSubtransactions = subtransactions.map((sub) => {
+            const subCategory = resolveCategoryInfo(sub.category_id, sub.category_name, localBudget);
+            return {
+                amount: sub.amount,
+                amount_currency: this.toCurrency(sub.amount, localBudget.currencyFormat),
+                category_group_name: subCategory.categoryGroupName,
+                category_id: sub.category_id ?? null,
+                category_name: subCategory.categoryName,
+                id: sub.id,
+                memo: sub.memo ?? null,
+                payee_id: sub.payee_id ?? null,
+                payee_name: resolvePayeeName(sub.payee_id, sub.payee_name, localBudget),
+                transaction_id: sub.transaction_id,
+                transfer_account_id: sub.transfer_account_id ?? null,
+            };
+        });
+        return {
+            account_id: tx.account_id,
+            account_name: accountName,
+            amount: tx.amount,
+            amount_currency: this.toCurrency(tx.amount, localBudget.currencyFormat),
+            approved: tx.approved,
+            category_group_name: categoryGroupName,
+            category_id: tx.category_id ?? null,
+            category_name: categoryName,
+            cleared: tx.cleared,
+            date: tx.date,
+            flag_color: tx.flag_color ?? null,
+            id: tx.id,
+            import_id: tx.import_id ?? null,
+            import_payee_name: tx.import_payee_name ?? null,
+            import_payee_name_original: tx.import_payee_name_original ?? null,
+            memo: tx.memo ?? null,
+            payee_id: tx.payee_id ?? null,
+            payee_name: payeeName,
+            subtransactions: enrichedSubtransactions,
+            transfer_account_id: tx.transfer_account_id ?? null,
+        };
+    }
+    /**
+     * Get transactions with optional filters.
+     *
+     * Reads from LocalBudget.transactions and applies filters locally.
+     * No API call is made - data comes from the synced local budget.
+     */
+    async getTransactions(budgetId, options = {}) {
+        const localBudget = await this.getLocalBudget(budgetId);
+        // Start with all non-deleted transactions
+        let transactions = localBudget.transactions.filter((tx) => tx.deleted !== true);
+        // Filter by account if specified
+        if (options.accountId !== undefined && options.accountId !== '') {
+            transactions = transactions.filter((tx) => tx.account_id === options.accountId);
+        }
+        // Filter by date if specified (since_date is inclusive)
+        if (options.sinceDate !== undefined && options.sinceDate !== '') {
+            const sinceDate = options.sinceDate;
+            transactions = transactions.filter((tx) => tx.date >= sinceDate);
+        }
+        // Filter by type
+        if (options.type === 'uncategorized') {
+            // Uncategorized = no category assigned
+            transactions = transactions.filter((tx) => tx.category_id === undefined || tx.category_id === null);
+        }
+        else if (options.type === 'unapproved') {
+            // Unapproved = not yet approved
+            transactions = transactions.filter((tx) => tx.approved !== true);
+        }
+        // Enrich and return
+        return transactions.map((tx) => this.enrichTransactionSummary(tx, localBudget));
+    }
+    /**
+     * Resolve an account selector to an account ID
+     */
+    async resolveAccountId(budgetId, selector) {
+        const cache = await this.getLocalBudget(budgetId);
+        // Validate selector has exactly one of name or id
+        const selectorHasName = selector.name !== undefined && selector.name !== '';
+        const selectorHasId = selector.id !== undefined && selector.id !== '';
+        if (selectorHasName && selectorHasId) {
+            throw new Error("Account selector must specify exactly one of: 'name' or 'id'.");
+        }
+        if (!selectorHasName && !selectorHasId) {
+            throw new Error("Account selector must specify 'name' or 'id'.");
+        }
+        // Find by ID
+        if (selectorHasId) {
+            const account = cache.accountById.get(selector.id ?? '');
+            if (account === undefined) {
+                const accountNames = cache.accounts
+                    .filter((a) => !a.closed && !a.deleted)
+                    .map((a) => a.name)
+                    .join(', ');
+                throw new Error(`No account found with ID: '${selector.id}'. Available accounts: ${accountNames}.`);
+            }
+            return account.id;
+        }
+        // Find by name (case-insensitive)
+        const nameLower = (selector.name ?? '').toLowerCase();
+        const account = cache.accountByName.get(nameLower);
+        if (account === undefined) {
+            const accountNames = cache.accounts
+                .filter((a) => !a.closed && !a.deleted)
+                .map((a) => a.name)
+                .join(', ');
+            throw new Error(`No account found with name: '${selector.name}'. Available accounts: ${accountNames}.`);
+        }
+        return account.id;
+    }
+    /**
+     * Get all accounts for a budget
+     */
+    async getAccounts(budgetId, includeClosed = false) {
+        const cache = await this.getLocalBudget(budgetId);
+        return cache.accounts
+            .filter((a) => !a.deleted && (includeClosed || !a.closed))
+            .map((a) => ({
+            balance: a.balance,
+            balance_currency: this.toCurrency(a.balance, cache.currencyFormat),
+            cleared_balance: a.cleared_balance,
+            cleared_balance_currency: this.toCurrency(a.cleared_balance, cache.currencyFormat),
+            closed: a.closed,
+            direct_import_in_error: a.direct_import_in_error ?? false,
+            direct_import_linked: a.direct_import_linked ?? false,
+            id: a.id,
+            name: a.name,
+            on_budget: a.on_budget,
+            type: a.type,
+            uncleared_balance: a.uncleared_balance,
+            uncleared_balance_currency: this.toCurrency(a.uncleared_balance, cache.currencyFormat),
+        }));
+    }
+    /**
+     * Get all categories for a budget
+     */
+    async getCategories(budgetId, includeHidden = false) {
+        const cache = await this.getLocalBudget(budgetId);
+        const flat = cache.categories
+            .filter((c) => !c.deleted && (includeHidden || !c.hidden))
+            .map((c) => ({
+            activity: c.activity,
+            balance: c.balance,
+            budgeted: c.budgeted,
+            category_group_id: c.category_group_id,
+            category_group_name: cache.categoryGroupNameById.get(c.category_group_id) ?? '',
+            deleted: c.deleted,
+            hidden: c.hidden,
+            id: c.id,
+            name: c.name,
+        }));
+        return { flat, groups: this.buildCategoryGroupsWithCategories(cache) };
+    }
+    /**
+     * Get all payees for a budget
+     */
+    async getPayees(budgetId) {
+        const cache = await this.getLocalBudget(budgetId);
+        return cache.payees
+            .filter((p) => !p.deleted)
+            .map((p) => ({
+            id: p.id,
+            name: p.name,
+            transfer_account_id: p.transfer_account_id ?? null,
+        }));
+    }
+    /**
+     * Update multiple transactions using the bulk PATCH endpoint
+     */
+    async updateTransactions(budgetId, updates) {
+        assertWriteAllowed('update_transactions');
+        const api = this.getApi();
+        // Map cleared string to YNAB enum
+        const mapCleared = (cleared) => {
+            if (cleared === undefined)
+                return undefined;
+            switch (cleared) {
+                case 'cleared':
+                    return TransactionClearedStatus.Cleared;
+                case 'reconciled':
+                    return TransactionClearedStatus.Reconciled;
+                case 'uncleared':
+                    return TransactionClearedStatus.Uncleared;
+                default:
+                    return undefined;
+            }
+        };
+        // Build the patch request with all supported fields
+        // TODO: Consider adding a merge mode that fetches existing subtransactions
+        // and merges with the provided ones, for a more intuitive UX. Currently,
+        // providing subtransactions will OVERWRITE all existing ones (matching YNAB API behavior).
+        const patchTransactions = updates.map((u) => ({
+            account_id: u.account_id,
+            amount: u.amount,
+            approved: u.approved,
+            category_id: u.category_id,
+            cleared: mapCleared(u.cleared),
+            date: u.date,
+            flag_color: u.flag_color,
+            id: u.id,
+            memo: u.memo,
+            payee_id: u.payee_id,
+            payee_name: u.payee_name,
+            subtransactions: u.subtransactions?.map((sub) => ({
+                amount: sub.amount,
+                category_id: sub.category_id,
+                memo: sub.memo,
+                payee_id: sub.payee_id,
+                payee_name: sub.payee_name,
+            })),
+        }));
+        const response = await api.transactions.updateTransactions(budgetId, {
+            transactions: patchTransactions,
+        });
+        // The API returns SaveTransactionsResponse which has transaction_ids for new ones
+        // and transactions array for updated ones
+        const updatedTxs = response.data.transactions ?? [];
+        // Always invalidate cache after write operations to ensure consistency
+        // (payees may be created, and we want fresh data for enrichment)
+        this.markNeedsSync(budgetId);
+        const freshCache = await this.getLocalBudget(budgetId);
+        const enriched = updatedTxs.map((tx) => this.enrichTransaction(tx, freshCache));
+        return {
+            updated: enriched,
+        };
+    }
+    /**
+     * Get currency format for a budget
+     */
+    async getCurrencyFormat(budgetId) {
+        const cache = await this.getLocalBudget(budgetId);
+        return cache.currencyFormat;
+    }
+    /**
+     * Get budget info (name, id) for journaling
+     */
+    async getBudgetInfo(budgetId) {
+        const budgets = await this.getBudgets();
+        const budget = budgets.find((b) => b.id === budgetId);
+        if (budget === undefined) {
+            return { id: budgetId, name: 'Unknown Budget' };
+        }
+        return { id: budget.id, name: budget.name };
+    }
+    /**
+     * Get raw budget detail for backup purposes
+     * Returns the complete budget data as returned by YNAB API
+     * (effectively a full budget export per YNAB docs)
+     */
+    async getBudgetByIdRaw(budgetId) {
+        const api = this.getApi();
+        const response = await api.budgets.getBudgetById(budgetId);
+        return {
+            budget: response.data.budget,
+            server_knowledge: response.data.server_knowledge,
+        };
+    }
+    /**
+     * Resolve a category selector to a category ID
+     */
+    async resolveCategoryId(budgetId, selector) {
+        const cache = await this.getLocalBudget(budgetId);
+        const selectorHasName = selector.name !== undefined && selector.name !== '';
+        const selectorHasId = selector.id !== undefined && selector.id !== '';
+        if (selectorHasName && selectorHasId) {
+            throw new Error("Category selector must specify exactly one of: 'name' or 'id'.");
+        }
+        if (!selectorHasName && !selectorHasId) {
+            throw new Error("Category selector must specify 'name' or 'id'.");
+        }
+        // Find by ID
+        if (selectorHasId) {
+            const category = cache.categoryById.get(selector.id ?? '');
+            if (category === undefined) {
+                const categoryNames = cache.categories
+                    .filter((c) => !c.deleted && !c.hidden)
+                    .slice(0, 20)
+                    .map((c) => c.name)
+                    .join(', ');
+                throw new Error(`No category found with ID: '${selector.id}'. Some available categories: ${categoryNames}...`);
+            }
+            return category.id;
+        }
+        // Find by name (case-insensitive)
+        const nameLower = (selector.name ?? '').toLowerCase();
+        const category = cache.categories.find((c) => !c.deleted && c.name.toLowerCase() === nameLower);
+        if (category === undefined) {
+            const categoryNames = cache.categories
+                .filter((c) => !c.deleted && !c.hidden)
+                .slice(0, 20)
+                .map((c) => c.name)
+                .join(', ');
+            throw new Error(`No category found with name: '${selector.name}'. Some available categories: ${categoryNames}...`);
+        }
+        return category.id;
+    }
+    /**
+     * Resolve a payee selector to a payee ID
+     */
+    async resolvePayeeId(budgetId, selector) {
+        const cache = await this.getLocalBudget(budgetId);
+        const selectorHasName = selector.name !== undefined && selector.name !== '';
+        const selectorHasId = selector.id !== undefined && selector.id !== '';
+        if (selectorHasName && selectorHasId) {
+            throw new Error("Payee selector must specify exactly one of: 'name' or 'id'.");
+        }
+        if (!selectorHasName && !selectorHasId) {
+            return null; // No payee specified
+        }
+        // Find by ID
+        if (selectorHasId) {
+            const payee = cache.payeeById.get(selector.id ?? '');
+            if (payee === undefined) {
+                throw new Error(`No payee found with ID: '${selector.id}'.`);
+            }
+            return payee.id;
+        }
+        // Find by name (case-insensitive) - return null if not found (will create new)
+        const nameLower = (selector.name ?? '').toLowerCase();
+        const payee = cache.payees.find((p) => !p.deleted && p.name.toLowerCase() === nameLower);
+        // Return null if not found - YNAB will create the payee
+        return payee?.id ?? null;
+    }
+    /**
+     * Get a single transaction by ID.
+     *
+     * Reads from LocalBudget.transactions - no API call is made.
+     */
+    async getTransaction(budgetId, transactionId) {
+        const localBudget = await this.getLocalBudget(budgetId);
+        // Find the transaction in local budget (check all, including deleted)
+        const transaction = localBudget.transactions.find((tx) => tx.id === transactionId);
+        if (transaction === undefined) {
+            throw new Error(`Transaction not found with ID: '${transactionId}'.`);
+        }
+        if (transaction.deleted === true) {
+            throw new Error(`Transaction '${transactionId}' has been deleted in YNAB.`);
+        }
+        return this.enrichTransactionSummary(transaction, localBudget);
+    }
+    /**
+     * Get scheduled transactions.
+     *
+     * Reads from LocalBudget.scheduledTransactions - no API call is made.
+     */
+    async getScheduledTransactions(budgetId) {
+        const localBudget = await this.getLocalBudget(budgetId);
+        return localBudget.scheduledTransactions
+            .filter((txn) => txn.deleted !== true)
+            .map((txn) => {
+            const account = localBudget.accountById.get(txn.account_id);
+            const accountName = account?.name ?? 'Unknown Account';
+            const payeeName = resolvePayeeName(txn.payee_id, null, localBudget);
+            const { categoryName } = resolveCategoryInfo(txn.category_id, null, localBudget);
+            // Get subtransactions for this scheduled transaction (O(1) lookup)
+            const subtransactions = (localBudget.scheduledSubtransactionsByScheduledTransactionId.get(txn.id) ?? []).filter((sub) => sub.deleted !== true);
+            return {
+                account_id: txn.account_id,
+                account_name: accountName,
+                amount: txn.amount,
+                amount_currency: this.toCurrency(txn.amount, localBudget.currencyFormat),
+                category_id: txn.category_id ?? null,
+                category_name: categoryName,
+                date_first: txn.date_first,
+                date_next: txn.date_next,
+                flag_color: txn.flag_color ?? null,
+                frequency: txn.frequency,
+                id: txn.id,
+                memo: txn.memo ?? null,
+                payee_id: txn.payee_id ?? null,
+                payee_name: payeeName,
+                subtransactions: subtransactions.map((sub) => ({
+                    amount: sub.amount,
+                    amount_currency: this.toCurrency(sub.amount, localBudget.currencyFormat),
+                    category_id: sub.category_id ?? null,
+                    category_name: resolveCategoryInfo(sub.category_id, sub.category_name, localBudget).categoryName,
+                    id: sub.id,
+                    memo: sub.memo ?? null,
+                    payee_id: sub.payee_id ?? null,
+                    payee_name: resolvePayeeName(sub.payee_id, sub.payee_name, localBudget),
+                    scheduled_transaction_id: sub.scheduled_transaction_id,
+                    transfer_account_id: sub.transfer_account_id ?? null,
+                })),
+                transfer_account_id: txn.transfer_account_id ?? null,
+            };
+        });
+    }
+    /**
+     * Get budget months list.
+     *
+     * Reads from LocalBudget.months - no API call is made.
+     */
+    async getBudgetMonths(budgetId) {
+        const localBudget = await this.getLocalBudget(budgetId);
+        return localBudget.months
+            .filter((month) => month.deleted !== true)
+            .map((month) => ({
+            activity: month.activity,
+            activity_currency: this.toCurrency(month.activity, localBudget.currencyFormat),
+            age_of_money: month.age_of_money ?? null,
+            budgeted: month.budgeted,
+            budgeted_currency: this.toCurrency(month.budgeted, localBudget.currencyFormat),
+            income: month.income,
+            income_currency: this.toCurrency(month.income, localBudget.currencyFormat),
+            month: month.month,
+            note: month.note ?? null,
+            to_be_budgeted: month.to_be_budgeted,
+            to_be_budgeted_currency: this.toCurrency(month.to_be_budgeted, localBudget.currencyFormat),
+        }));
+    }
+    /**
+     * Get budget month detail with categories.
+     *
+     * Reads from LocalBudget.months - no API call is made.
+     */
+    async getBudgetMonth(budgetId, month) {
+        const localBudget = await this.getLocalBudget(budgetId);
+        // Find the month in local budget (check all, including deleted)
+        const monthData = localBudget.months.find((m) => m.month === month);
+        if (monthData === undefined) {
+            throw new Error(`Budget month not found: '${month}'.`);
+        }
+        if (monthData.deleted === true) {
+            throw new Error(`Budget month '${month}' has been deleted in YNAB.`);
+        }
+        const categories = monthData.categories
+            .filter((c) => !c.deleted)
+            .map((c) => ({
+            activity: c.activity,
+            activity_currency: this.toCurrency(c.activity, localBudget.currencyFormat),
+            balance: c.balance,
+            balance_currency: this.toCurrency(c.balance, localBudget.currencyFormat),
+            budgeted: c.budgeted,
+            budgeted_currency: this.toCurrency(c.budgeted, localBudget.currencyFormat),
+            category_group_id: c.category_group_id,
+            category_group_name: localBudget.categoryGroupNameById.get(c.category_group_id) ?? '',
+            goal_percentage_complete: c.goal_percentage_complete ?? null,
+            goal_target: c.goal_target ?? null,
+            goal_type: c.goal_type ?? null,
+            hidden: c.hidden,
+            id: c.id,
+            name: c.name,
+        }));
+        return {
+            activity: monthData.activity,
+            activity_currency: this.toCurrency(monthData.activity, localBudget.currencyFormat),
+            age_of_money: monthData.age_of_money ?? null,
+            budgeted: monthData.budgeted,
+            budgeted_currency: this.toCurrency(monthData.budgeted, localBudget.currencyFormat),
+            categories,
+            income: monthData.income,
+            income_currency: this.toCurrency(monthData.income, localBudget.currencyFormat),
+            month: monthData.month,
+            note: monthData.note ?? null,
+            to_be_budgeted: monthData.to_be_budgeted,
+            to_be_budgeted_currency: this.toCurrency(monthData.to_be_budgeted, localBudget.currencyFormat),
+        };
+    }
+    /**
+     * Create one or more transactions
+     */
+    async createTransactions(budgetId, transactions) {
+        assertWriteAllowed('create_transactions');
+        const api = this.getApi();
+        const response = await api.transactions.createTransaction(budgetId, {
+            transactions: transactions.map((transaction) => ({
+                account_id: transaction.account_id,
+                amount: transaction.amount,
+                approved: transaction.approved ?? false,
+                category_id: transaction.category_id,
+                cleared: transaction.cleared === 'reconciled'
+                    ? TransactionClearedStatus.Reconciled
+                    : transaction.cleared === 'cleared'
+                        ? TransactionClearedStatus.Cleared
+                        : TransactionClearedStatus.Uncleared,
+                date: transaction.date,
+                flag_color: transaction.flag_color,
+                memo: transaction.memo,
+                payee_id: transaction.payee_id,
+                payee_name: transaction.payee_name,
+                subtransactions: transaction.subtransactions?.map((sub) => ({
+                    amount: sub.amount,
+                    category_id: sub.category_id,
+                    memo: sub.memo,
+                    payee_id: sub.payee_id,
+                    payee_name: sub.payee_name,
+                })),
+            })),
+        });
+        // Invalidate cache since payees may have been created
+        this.markNeedsSync(budgetId);
+        const createdTransactions = response.data.transactions ?? [];
+        const duplicateImportIds = response.data.duplicate_import_ids ?? [];
+        const newCache = await this.getLocalBudget(budgetId);
+        const enriched = createdTransactions.map((t) => this.enrichTransaction(t, newCache));
+        return {
+            created: enriched,
+            duplicates: duplicateImportIds,
+        };
+    }
+    /**
+     * Delete a transaction
+     */
+    async deleteTransaction(budgetId, transactionId) {
+        assertWriteAllowed('delete_transaction');
+        const cache = await this.getLocalBudget(budgetId);
+        const api = this.getApi();
+        const response = await api.transactions.deleteTransaction(budgetId, transactionId);
+        return {
+            deleted: this.enrichTransaction(response.data.transaction, cache),
+        };
+    }
+    /**
+     * Import transactions from linked accounts
+     */
+    async importTransactions(budgetId) {
+        assertWriteAllowed('import_transactions');
+        const api = this.getApi();
+        const response = await api.transactions.importTransactions(budgetId);
+        // Invalidate cache since import may create new payees
+        this.markNeedsSync(budgetId);
+        return {
+            imported_count: response.data.transaction_ids.length,
+            transaction_ids: response.data.transaction_ids,
+        };
+    }
+    /**
+     * Create a new account
+     */
+    async createAccount(budgetId, name, type, balance) {
+        assertWriteAllowed('create_account');
+        const api = this.getApi();
+        const response = await api.accounts.createAccount(budgetId, {
+            account: {
+                balance,
+                name,
+                type,
+            },
+        });
+        // Invalidate cache since we've added a new account
+        this.markNeedsSync(budgetId);
+        const account = response.data.account;
+        const cache = await this.getLocalBudget(budgetId);
+        return {
+            balance: account.balance,
+            balance_currency: this.toCurrency(account.balance, cache.currencyFormat),
+            cleared_balance: account.cleared_balance,
+            cleared_balance_currency: this.toCurrency(account.cleared_balance, cache.currencyFormat),
+            closed: account.closed,
+            direct_import_in_error: account.direct_import_in_error ?? false,
+            direct_import_linked: account.direct_import_linked ?? false,
+            id: account.id,
+            name: account.name,
+            on_budget: account.on_budget,
+            type: account.type,
+            uncleared_balance: account.uncleared_balance,
+            uncleared_balance_currency: this.toCurrency(account.uncleared_balance, cache.currencyFormat),
+        };
+    }
+    /**
+     * Update category budget for a month
+     */
+    async updateCategoryBudget(budgetId, month, categoryId, budgeted) {
+        assertWriteAllowed('update_category_budget');
+        const cache = await this.getLocalBudget(budgetId);
+        const api = this.getApi();
+        const response = await api.categories.updateMonthCategory(budgetId, month, categoryId, {
+            category: {
+                budgeted,
+            },
+        });
+        const c = response.data.category;
+        return {
+            activity: c.activity,
+            activity_currency: this.toCurrency(c.activity, cache.currencyFormat),
+            balance: c.balance,
+            balance_currency: this.toCurrency(c.balance, cache.currencyFormat),
+            budgeted: c.budgeted,
+            budgeted_currency: this.toCurrency(c.budgeted, cache.currencyFormat),
+            category_group_id: c.category_group_id,
+            category_group_name: cache.categoryGroupNameById.get(c.category_group_id) ?? '',
+            goal_percentage_complete: c.goal_percentage_complete ?? null,
+            goal_target: c.goal_target ?? null,
+            goal_type: c.goal_type ?? null,
+            hidden: c.hidden,
+            id: c.id,
+            name: c.name,
+        };
+    }
+    /**
+     * Clear all local budgets (useful for testing or forcing full re-sync)
+     */
+    clearLocalBudgets() {
+        this.budgets = null;
+        this.localBudgets.clear();
+        this.previousBudgetDetails.clear();
+    }
+    /**
+     * Force sync for a specific budget or all budgets.
+     * If budgetId provided, marks that budget as needing sync.
+     * If no budgetId provided, clears all local budgets (forcing full re-sync on next access).
+     *
+     * @deprecated Use markNeedsSync() for individual budgets. This method
+     * is kept for backwards compatibility but will be removed in a future version.
+     */
+    invalidateCache(budgetId) {
+        if (budgetId !== undefined) {
+            this.markNeedsSync(budgetId);
+        }
+        else {
+            this.localBudgets.clear();
+            this.budgets = null;
+        }
+    }
+}
+// Export singleton instance
+export const ynabClient = new YnabClient();