ynab-mcp-deluxe 0.1.9

package/dist/drift-detection.js

@@ -0,0 +1,366 @@
+/**
+ * Drift detection for LocalBudget.
+ *
+ * This module compares a merged LocalBudget (base + deltas) against a fresh
+ * full budget fetch to detect any discrepancies in our merge logic.
+ *
+ * When drift is detected:
+ * 1. Log detailed warnings showing what differs
+ * 2. Self-heal by replacing local budget with the full fetch result
+ */
+import deepDiff from 'deep-diff';
+// ============================================================================
+// Type Guards for deep-diff types
+// ============================================================================
+/**
+ * Type guard for DiffNew (kind: "N") - entity exists in truth but not in merged.
+ * Indicates something was added in the truth that the merge didn't produce.
+ */
+function isDiffNew(d) {
+    return d.kind === 'N';
+}
+/**
+ * Type guard for DiffDeleted (kind: "D") - entity exists in merged but not in truth.
+ * Indicates something extra in merged that shouldn't be there.
+ */
+function isDiffDeleted(d) {
+    return d.kind === 'D';
+}
+/**
+ * Type guard for DiffEdit (kind: "E") - entity exists in both but values differ.
+ * Indicates a field value mismatch between merged and truth.
+ */
+function isDiffEdit(d) {
+    return d.kind === 'E';
+}
+/**
+ * Type guard for DiffArray (kind: "A") - array-specific change at an index.
+ * Indicates an element-level change within an array.
+ */
+function isDiffArray(d) {
+    return d.kind === 'A';
+}
+/**
+ * Per-budget drift check state.
+ * Using a Map keyed by budgetId ensures each budget tracks its own
+ * drift check frequency independently, preventing race conditions
+ * when multiple budgets are synced concurrently.
+ */
+const driftCheckStateByBudget = new Map();
+/**
+ * Get or create drift check state for a specific budget.
+ */
+function getDriftCheckState(budgetId) {
+    let state = driftCheckStateByBudget.get(budgetId);
+    if (state === undefined) {
+        state = {
+            checkEvaluationCount: 0,
+            lastDriftCheckAt: null,
+        };
+        driftCheckStateByBudget.set(budgetId, state);
+    }
+    return state;
+}
+// ============================================================================
+// Environment Variable Helpers
+// ============================================================================
+/**
+ * Check if drift detection is enabled.
+ *
+ * Default: true (enabled)
+ * Set YNAB_DRIFT_DETECTION=false to disable
+ */
+export function isDriftDetectionEnabled() {
+    const value = process.env['YNAB_DRIFT_DETECTION'];
+    // Default to true if not set
+    if (value === undefined || value === '') {
+        return true;
+    }
+    // Explicitly disabled
+    return value !== 'false' && value !== '0';
+}
+/**
+ * Check if "always full sync" mode is enabled.
+ * When enabled, skip delta queries entirely and always fetch the full budget.
+ *
+ * Default: false (use delta sync for performance)
+ * Set YNAB_ALWAYS_FULL_SYNC=true to enable
+ */
+export function isAlwaysFullSyncEnabled() {
+    const value = process.env['YNAB_ALWAYS_FULL_SYNC'];
+    return value === 'true' || value === '1';
+}
+/**
+ * Get the drift check interval in number of syncs.
+ * In production, we don't need to check every sync - periodic checks are sufficient.
+ *
+ * Default: 1 (check every sync - good for development/alpha)
+ * Set YNAB_DRIFT_CHECK_INTERVAL_SYNCS to change
+ */
+export function getDriftCheckIntervalSyncs() {
+    const value = process.env['YNAB_DRIFT_CHECK_INTERVAL_SYNCS'];
+    if (value === undefined || value === '') {
+        return 1; // Default: check every sync
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed < 1) {
+        return 1;
+    }
+    return parsed;
+}
+/**
+ * Get the drift check interval in minutes.
+ * Alternative to sync-count-based checking.
+ *
+ * Default: 0 (disabled - use sync count instead)
+ * Set YNAB_DRIFT_CHECK_INTERVAL_MINUTES to enable time-based checking
+ */
+export function getDriftCheckIntervalMinutes() {
+    const value = process.env['YNAB_DRIFT_CHECK_INTERVAL_MINUTES'];
+    if (value === undefined || value === '') {
+        return 0; // Disabled by default
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed < 0) {
+        return 0;
+    }
+    return parsed;
+}
+// ============================================================================
+// Drift Check Logic
+// ============================================================================
+/**
+ * Determine if a drift check should be performed based on frequency settings.
+ * Call this before performing a drift check to respect rate limiting.
+ *
+ * @param budgetId - The budget ID to check drift state for
+ * @returns true if a drift check should be performed
+ */
+export function shouldPerformDriftCheck(budgetId) {
+    if (!isDriftDetectionEnabled()) {
+        return false;
+    }
+    // Always full sync mode means we don't need drift checks
+    // (we're always getting the full budget anyway)
+    if (isAlwaysFullSyncEnabled()) {
+        return false;
+    }
+    // Get per-budget state
+    const state = getDriftCheckState(budgetId);
+    // Increment the evaluation count for this budget.
+    // This tracks how many times we've checked whether to perform a drift check,
+    // NOT how many actual syncs have occurred. A drift check is triggered when
+    // this count reaches a multiple of the configured interval.
+    state.checkEvaluationCount++;
+    // Check if we've reached the interval threshold
+    const checkInterval = getDriftCheckIntervalSyncs();
+    if (state.checkEvaluationCount % checkInterval === 0) {
+        return true;
+    }
+    // Check time interval (if configured)
+    const minuteInterval = getDriftCheckIntervalMinutes();
+    if (minuteInterval > 0 && state.lastDriftCheckAt !== null) {
+        const elapsed = Date.now() - state.lastDriftCheckAt.getTime();
+        const elapsedMinutes = elapsed / (1000 * 60);
+        if (elapsedMinutes >= minuteInterval) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Record that a drift check was performed for a specific budget.
+ * Call this after completing a drift check.
+ *
+ * @param budgetId - The budget ID to record the drift check for
+ */
+export function recordDriftCheck(budgetId) {
+    const state = getDriftCheckState(budgetId);
+    state.lastDriftCheckAt = new Date();
+}
+/**
+ * Reset drift check state (useful for testing).
+ *
+ * @param budgetId - Optional budget ID to reset. If not provided, resets all budgets.
+ */
+export function resetDriftCheckState(budgetId) {
+    if (budgetId !== undefined) {
+        // Reset specific budget
+        driftCheckStateByBudget.delete(budgetId);
+    }
+    else {
+        // Reset all budgets
+        driftCheckStateByBudget.clear();
+    }
+}
+/**
+ * Sort an array of entities by their `id` field for consistent comparison.
+ * This ensures that arrays are compared by content, not by position.
+ */
+function sortById(arr) {
+    return [...arr].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Prepare months for comparison by sorting by `month` key and sorting
+ * nested `categories` arrays by `id`.
+ */
+function prepareMonths(months) {
+    return [...months]
+        .map((m) => ({
+        ...m,
+        categories: sortById(m.categories),
+    }))
+        .sort((a, b) => a.month.localeCompare(b.month));
+}
+/**
+ * Prepare a LocalBudget for comparison by converting Maps to plain objects,
+ * removing non-comparable fields, and normalizing array order.
+ *
+ * Arrays are sorted by ID to ensure comparison is by content, not position.
+ * This is necessary because delta sync may return entities in a different
+ * order than a full fetch.
+ *
+ * @param budget - The LocalBudget to prepare
+ * @returns A plain object suitable for deep comparison
+ */
+function prepareForComparison(budget) {
+    // Only compare the data arrays, not the lookup maps or metadata
+    // Sort all arrays by ID to compare by content, not position
+    return {
+        accounts: sortById(budget.accounts),
+        budgetId: budget.budgetId,
+        budgetName: budget.budgetName,
+        categories: sortById(budget.categories),
+        categoryGroups: sortById(budget.categoryGroups),
+        currencyFormat: budget.currencyFormat,
+        months: prepareMonths(budget.months),
+        payeeLocations: sortById(budget.payeeLocations),
+        payees: sortById(budget.payees),
+        scheduledSubtransactions: sortById(budget.scheduledSubtransactions),
+        scheduledTransactions: sortById(budget.scheduledTransactions),
+        // Skip serverKnowledge as it will differ
+        subtransactions: sortById(budget.subtransactions),
+        transactions: sortById(budget.transactions),
+    };
+}
+/**
+ * Get a human-readable path from a diff result.
+ */
+function formatDiffPath(diffResult) {
+    if (diffResult.path === undefined) {
+        return '(root)';
+    }
+    return diffResult.path.map((p) => String(p)).join('.');
+}
+/**
+ * Summarize differences by top-level category.
+ */
+function summarizeDifferences(differences) {
+    const summary = {};
+    for (const d of differences) {
+        // d.path is typed as any[] | undefined in deep-diff, so we handle it safely
+        const pathArray = d.path;
+        const firstPath = pathArray?.[0];
+        const category = firstPath !== undefined ? String(firstPath) : 'unknown';
+        summary[category] = (summary[category] ?? 0) + 1;
+    }
+    return summary;
+}
+/**
+ * Compare a merged LocalBudget against a "truth" budget from a full fetch.
+ *
+ * @param mergedBudget - The budget built from base + delta merges
+ * @param truthBudget - The budget from a fresh full fetch (source of truth)
+ * @returns Detailed comparison result
+ */
+export function checkForDrift(mergedBudget, truthBudget) {
+    const serverKnowledgeMismatch = mergedBudget.serverKnowledge !== truthBudget.serverKnowledge;
+    // Prepare budgets for comparison (strip Maps and metadata)
+    const mergedData = prepareForComparison(mergedBudget);
+    const truthData = prepareForComparison(truthBudget);
+    // Perform deep comparison
+    const differences = deepDiff(mergedData, truthData) ?? [];
+    return {
+        differenceCount: differences.length,
+        differenceSummary: summarizeDifferences(differences),
+        differences,
+        hasDrift: differences.length > 0,
+        mergedServerKnowledge: mergedBudget.serverKnowledge,
+        serverKnowledgeMismatch,
+        truthServerKnowledge: truthBudget.serverKnowledge,
+    };
+}
+/**
+ * Log drift check results appropriately based on outcome.
+ *
+ * @param result - The drift check result
+ * @param budgetId - The budget ID (for logging context)
+ * @param log - The logger to use
+ */
+export function logDriftCheckResult(result, budgetId, log) {
+    // Log server knowledge mismatch warning
+    if (result.serverKnowledgeMismatch) {
+        log.warn('⚠️ Server knowledge mismatch during drift check', {
+            budgetId,
+            mergedServerKnowledge: result.mergedServerKnowledge,
+            note: 'External changes likely occurred between queries. Differences may be expected.',
+            truthServerKnowledge: result.truthServerKnowledge,
+        });
+    }
+    if (!result.hasDrift) {
+        // Success! No drift detected
+        log.info('✅ Drift check passed - merge logic validated', {
+            budgetId,
+            serverKnowledge: {
+                merged: result.mergedServerKnowledge,
+                truth: result.truthServerKnowledge,
+            },
+        });
+        return;
+    }
+    // Drift detected - log detailed warning
+    log.error('🚨 DRIFT DETECTED - merge logic produced different result', {
+        budgetId,
+        differenceCount: result.differenceCount,
+        differenceSummary: result.differenceSummary,
+    });
+    // Log first few differences in detail (limit to avoid log spam)
+    const maxDetailsToLog = 5;
+    const differencesToLog = result.differences.slice(0, maxDetailsToLog);
+    for (let i = 0; i < differencesToLog.length; i++) {
+        const d = differencesToLog[i];
+        if (d === undefined)
+            continue;
+        const path = formatDiffPath(d);
+        // Use type guards for proper type narrowing
+        if (isDiffNew(d)) {
+            // New in truth (missing in merged)
+            log.error(`  [${i + 1}] MISSING: ${path}`, {
+                truthValue: d.rhs,
+            });
+        }
+        else if (isDiffDeleted(d)) {
+            // Deleted in truth (extra in merged)
+            log.error(`  [${i + 1}] EXTRA: ${path}`, {
+                mergedValue: d.lhs,
+            });
+        }
+        else if (isDiffEdit(d)) {
+            // Edited (value differs)
+            log.error(`  [${i + 1}] DIFFERS: ${path}`, {
+                merged: d.lhs,
+                truth: d.rhs,
+            });
+        }
+        else if (isDiffArray(d)) {
+            // Array change
+            log.error(`  [${i + 1}] ARRAY CHANGE: ${path}[${d.index}]`, {
+                item: d.item,
+            });
+        }
+    }
+    if (result.differenceCount > maxDetailsToLog) {
+        log.error(`  ... and ${result.differenceCount - maxDetailsToLog} more differences`);
+    }
+    log.info('🔧 Self-healing: Replacing local budget with full fetch result');
+}

package/dist/drift-snapshot.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Drift Snapshot Collection
+ *
+ * Saves drift detection artifacts for later analysis when drift is detected.
+ * This allows passive collection of real-world drift cases while development
+ * continues with full sync (guaranteed correct).
+ */
+import type { DriftCheckResult } from './drift-detection.js';
+import type { LocalBudget } from './types.js';
+import type { BudgetDetail } from 'ynab';
+/**
+ * Logger interface matching FastMCP's context log
+ */
+interface ContextLog {
+    debug: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+}
+/**
+ * Get the drift sample rate (1 in N drift occurrences are saved).
+ * Default: 1 (save all drift occurrences)
+ * Set YNAB_DRIFT_SAMPLE_RATE to change.
+ */
+export declare function getDriftSampleRate(): number;
+/**
+ * Check if this drift occurrence should be sampled (saved).
+ * Increments internal counter and checks against sample rate.
+ */
+export declare function shouldSampleDrift(): boolean;
+/**
+ * Reset drift occurrence counter (useful for testing).
+ */
+export declare function resetDriftOccurrenceCount(): void;
+/**
+ * Get the drift snapshots directory.
+ * ~/.config/ynab-mcp-deluxe/drift-snapshots/
+ */
+export declare function getDriftSnapshotsDir(): string;
+/**
+ * Artifacts to save when drift is detected.
+ */
+export interface DriftSnapshotArtifacts {
+    /** The budget ID */
+    budgetId: string;
+    /** The delta API response */
+    deltaResponse: BudgetDetail;
+    /** The drift check result with differences */
+    driftResult: DriftCheckResult;
+    /** The full API response (truth) */
+    fullResponse: BudgetDetail;
+    /** The merged budget (from applying delta to previous) */
+    mergedBudget: LocalBudget;
+    /** The previous full budget (base for merge) */
+    previousFullResponse: BudgetDetail;
+    /** Server knowledge values */
+    serverKnowledge: {
+        afterDelta: number;
+        afterFull: number;
+        previous: number;
+    };
+}
+/**
+ * Save drift snapshot artifacts to disk.
+ *
+ * Creates a timestamped directory with all artifacts for later analysis.
+ *
+ * @param artifacts - The drift snapshot artifacts to save
+ * @param log - Logger for debug output
+ * @returns The path to the saved snapshot directory
+ */
+export declare function saveDriftSnapshot(artifacts: DriftSnapshotArtifacts, log: ContextLog): Promise<string>;
+export {};
+//# sourceMappingURL=drift-snapshot.d.ts.map

package/dist/drift-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-snapshot.d.ts","sourceRoot":"","sources":["../src/drift-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,MAAM,CAAC;AAMvC;;GAEG;AACH,UAAU,UAAU;IAClB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAU3C;AAKD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAI3C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,aAAa,EAAE,YAAY,CAAC;IAC5B,8CAA8C;IAC9C,WAAW,EAAE,gBAAgB,CAAC;IAC9B,oCAAoC;IACpC,YAAY,EAAE,YAAY,CAAC;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,WAAW,CAAC;IAC1B,gDAAgD;IAChD,oBAAoB,EAAE,YAAY,CAAC;IACnC,8BAA8B;IAC9B,eAAe,EAAE;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AA0BD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,MAAM,CAAC,CA8DjB"}

package/dist/drift-snapshot.js

@@ -0,0 +1,120 @@
+/**
+ * Drift Snapshot Collection
+ *
+ * Saves drift detection artifacts for later analysis when drift is detected.
+ * This allows passive collection of real-world drift cases while development
+ * continues with full sync (guaranteed correct).
+ */
+import * as fs from 'node:fs/promises';
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+/**
+ * Get the drift sample rate (1 in N drift occurrences are saved).
+ * Default: 1 (save all drift occurrences)
+ * Set YNAB_DRIFT_SAMPLE_RATE to change.
+ */
+export function getDriftSampleRate() {
+    const value = process.env['YNAB_DRIFT_SAMPLE_RATE'];
+    if (value === undefined || value === '') {
+        return 1; // Default: save all
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed < 1) {
+        return 1;
+    }
+    return parsed;
+}
+// Module-level counter for sample rate
+let driftOccurrenceCount = 0;
+/**
+ * Check if this drift occurrence should be sampled (saved).
+ * Increments internal counter and checks against sample rate.
+ */
+export function shouldSampleDrift() {
+    driftOccurrenceCount++;
+    const sampleRate = getDriftSampleRate();
+    return driftOccurrenceCount % sampleRate === 0;
+}
+/**
+ * Reset drift occurrence counter (useful for testing).
+ */
+export function resetDriftOccurrenceCount() {
+    driftOccurrenceCount = 0;
+}
+/**
+ * Get the drift snapshots directory.
+ * ~/.config/ynab-mcp-deluxe/drift-snapshots/
+ */
+export function getDriftSnapshotsDir() {
+    return path.join(homedir(), '.config', 'ynab-mcp-deluxe', 'drift-snapshots');
+}
+/**
+ * Serialize a LocalBudget for saving (convert Maps to objects).
+ */
+function serializeLocalBudget(budget) {
+    return {
+        accounts: budget.accounts,
+        budgetId: budget.budgetId,
+        budgetName: budget.budgetName,
+        categories: budget.categories,
+        categoryGroups: budget.categoryGroups,
+        currencyFormat: budget.currencyFormat,
+        lastSyncedAt: budget.lastSyncedAt.toISOString(),
+        months: budget.months,
+        needsSync: budget.needsSync,
+        payeeLocations: budget.payeeLocations,
+        payees: budget.payees,
+        scheduledSubtransactions: budget.scheduledSubtransactions,
+        scheduledTransactions: budget.scheduledTransactions,
+        serverKnowledge: budget.serverKnowledge,
+        subtransactions: budget.subtransactions,
+        transactions: budget.transactions,
+    };
+}
+/**
+ * Save drift snapshot artifacts to disk.
+ *
+ * Creates a timestamped directory with all artifacts for later analysis.
+ *
+ * @param artifacts - The drift snapshot artifacts to save
+ * @param log - Logger for debug output
+ * @returns The path to the saved snapshot directory
+ */
+export async function saveDriftSnapshot(artifacts, log) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const snapshotDir = path.join(getDriftSnapshotsDir(), `${timestamp}_${artifacts.budgetId}`);
+    try {
+        // Ensure directory exists
+        await fs.mkdir(snapshotDir, { recursive: true });
+        // Prepare summary
+        const summary = {
+            budgetId: artifacts.budgetId,
+            differenceCount: artifacts.driftResult.differenceCount,
+            differenceSummary: artifacts.driftResult.differenceSummary,
+            savedAt: new Date().toISOString(),
+            serverKnowledge: artifacts.serverKnowledge,
+            serverKnowledgeMismatch: artifacts.driftResult.serverKnowledgeMismatch,
+        };
+        // Save all artifacts in parallel
+        await Promise.all([
+            fs.writeFile(path.join(snapshotDir, 'summary.json'), JSON.stringify(summary, null, 2)),
+            fs.writeFile(path.join(snapshotDir, 'previous-full.json'), JSON.stringify(artifacts.previousFullResponse, null, 2)),
+            fs.writeFile(path.join(snapshotDir, 'delta-response.json'), JSON.stringify(artifacts.deltaResponse, null, 2)),
+            fs.writeFile(path.join(snapshotDir, 'merged-budget.json'), JSON.stringify(serializeLocalBudget(artifacts.mergedBudget), null, 2)),
+            fs.writeFile(path.join(snapshotDir, 'full-response.json'), JSON.stringify(artifacts.fullResponse, null, 2)),
+            fs.writeFile(path.join(snapshotDir, 'differences.json'), JSON.stringify(artifacts.driftResult.differences, null, 2)),
+        ]);
+        log.info('💾 Drift snapshot saved for later analysis', {
+            differenceCount: artifacts.driftResult.differenceCount,
+            path: snapshotDir,
+        });
+        return snapshotDir;
+    }
+    catch (error) {
+        log.error('Failed to save drift snapshot', {
+            error: error instanceof Error ? error.message : String(error),
+            snapshotDir,
+        });
+        throw error;
+    }
+}

package/dist/helpers.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Helper functions for the YNAB MCP server
+ */
+import type { CategoryDistribution, EnrichedTransaction, TransactionSortBy } from './types.js';
+/**
+ * Apply a JMESPath query to data
+ * @throws Error with helpful message if query is invalid
+ */
+export declare function applyJMESPath<T>(data: T, query: string): unknown;
+/**
+ * Sort transactions by the specified criteria
+ */
+export declare function sortTransactions(transactions: EnrichedTransaction[], sortBy: TransactionSortBy): EnrichedTransaction[];
+/**
+ * Filter transactions by payee name (case-insensitive partial match)
+ */
+export declare function filterByPayee(transactions: EnrichedTransaction[], payeeContains: string): EnrichedTransaction[];
+/**
+ * Filter transactions by date range
+ */
+export declare function filterByDateRange(transactions: EnrichedTransaction[], sinceDate?: string, untilDate?: string): EnrichedTransaction[];
+/**
+ * Filter transactions by account ID
+ */
+export declare function filterByAccount(transactions: EnrichedTransaction[], accountId: string): EnrichedTransaction[];
+/**
+ * Calculate category distribution for a set of transactions
+ */
+export declare function calculateCategoryDistribution(transactions: EnrichedTransaction[]): CategoryDistribution[];
+/**
+ * Create an MCP error response
+ */
+export declare function createErrorResponse(message: string): {
+    content: {
+        text: string;
+        type: 'text';
+    }[];
+    isError: true;
+};
+/**
+ * Validate a selector has exactly one of name or id
+ */
+export declare function validateSelector(selector: {
+    id?: string;
+    name?: string;
+} | undefined, entityType: string): void;
+/**
+ * Check if a value looks like it might be a JMESPath query result
+ * (i.e., it's been transformed by a projection)
+ */
+export declare function isTransformed(value: unknown): boolean;
+/**
+ * Create an enhanced MCP error response with context from YNAB errors
+ *
+ * Extracts HTTP status codes and error details from YNAB SDK errors
+ * to provide actionable error messages for the LLM.
+ */
+export declare function createEnhancedErrorResponse(error: unknown, operation: string): Promise<{
+    content: {
+        text: string;
+        type: 'text';
+    }[];
+    isError: true;
+}>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAchE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,mBAAmB,EAAE,EACnC,MAAM,EAAE,iBAAiB,GACxB,mBAAmB,EAAE,CAqBvB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,mBAAmB,EAAE,EACnC,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CAavB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,mBAAmB,EAAE,EACnC,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,mBAAmB,EAAE,CAQvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,mBAAmB,EAAE,EACnC,SAAS,EAAE,MAAM,GAChB,mBAAmB,EAAE,CAEvB;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,mBAAmB,EAAE,GAClC,oBAAoB,EAAE,CAoCxB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IACxC,OAAO,EAAE,IAAI,CAAC;CACf,CAKA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,SAAS,EAClD,UAAU,EAAE,MAAM,GACjB,IAAI,CAWN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOrD;AAiDD;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAC,OAAO,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAC,CAAC,CAoDnE"}