ynab-mcp-deluxe 0.1.9

package/dist/sync-history.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Sync history persistence utilities.
+ *
+ * Every sync response is saved to disk, creating an automatic incremental backup trail.
+ * This replaces the auto-backup functionality with continuous, granular backups.
+ *
+ * Directory structure:
+ * ~/.config/ynab-mcp-deluxe/sync-history/[budgetId]/
+ *   - 20260125T143022Z-full.json    # Initial sync
+ *   - 20260125T153022Z-delta.json   # Delta sync
+ *   - ...
+ */
+import type { SyncType } 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 base sync history directory path.
+ * ~/.config/ynab-mcp-deluxe/sync-history/
+ */
+export declare function getSyncHistoryBaseDir(): string;
+/**
+ * Validate that a budgetId is safe to use in file paths.
+ * YNAB budget IDs are UUIDs (alphanumeric with hyphens).
+ * This prevents path traversal attacks with malicious budgetId values.
+ *
+ * @param budgetId - The budget ID to validate
+ * @returns true if the budgetId is safe for use in paths
+ */
+export declare function isValidBudgetIdForPath(budgetId: string): boolean;
+/**
+ * Get the sync history directory for a specific budget.
+ * ~/.config/ynab-mcp-deluxe/sync-history/[budgetId]/
+ *
+ * @param budgetId - The budget ID (must be a valid UUID format)
+ * @throws Error if budgetId contains invalid characters (path traversal protection)
+ */
+export declare function getSyncHistoryDir(budgetId: string): string;
+/**
+ * Ensure the sync history directory exists for a budget.
+ * Creates the directory tree if it doesn't exist.
+ */
+export declare function ensureSyncHistoryDir(budgetId: string): Promise<void>;
+/**
+ * Generate sync history filename with timestamp and sync type.
+ * Format: YYYYMMDDTHHMMSSZ-[full|delta].json
+ *
+ * Uses compact ISO 8601 format for easy sorting and readability.
+ * Example: 20260125T143022Z-full.json
+ */
+export declare function generateSyncFilename(syncType: SyncType): string;
+/**
+ * Persist a sync response to disk.
+ *
+ * This function is designed to be fail-safe: if the write fails,
+ * it logs a warning but does not throw. The sync operation should
+ * continue even if persistence fails.
+ *
+ * @param budgetId - The budget ID
+ * @param syncType - 'full' or 'delta'
+ * @param budget - The budget data from YNAB API
+ * @param serverKnowledge - The server_knowledge from this sync
+ * @param previousServerKnowledge - For delta syncs, the previous server_knowledge
+ * @param log - Logger for debug/error output
+ * @returns The file path if successful, null if failed
+ */
+export declare function persistSyncResponse(budgetId: string, syncType: SyncType, budget: BudgetDetail, serverKnowledge: number, previousServerKnowledge: number | null, log: ContextLog): Promise<string | null>;
+/**
+ * Result of clearing sync history
+ */
+export interface ClearSyncHistoryResult {
+    /** Budget IDs that were cleared (or 'all' if no specific budget) */
+    budgetsCleared: string[];
+    /** Any errors encountered (non-fatal) */
+    errors: string[];
+    /** Number of files deleted */
+    filesDeleted: number;
+}
+/**
+ * Clear sync history for a specific budget or all budgets.
+ *
+ * @param budgetId - Optional budget ID to clear. If not provided, clears all budgets.
+ * @param log - Logger for debug/error output
+ * @returns Summary of the clear operation
+ */
+export declare function clearSyncHistory(budgetId: string | null, log: ContextLog): Promise<ClearSyncHistoryResult>;
+export {};
+//# sourceMappingURL=sync-history.d.ts.map

package/dist/sync-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-history.d.ts","sourceRoot":"","sources":["../src/sync-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAmB,QAAQ,EAAC,MAAM,YAAY,CAAC;AAC3D,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;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKhE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAS/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,MAAM,EACvB,uBAAuB,EAAE,MAAM,GAAG,IAAI,EACtC,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4CxB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,sBAAsB,CAAC,CAmEjC"}

package/dist/sync-history.js

@@ -0,0 +1,205 @@
+/**
+ * Sync history persistence utilities.
+ *
+ * Every sync response is saved to disk, creating an automatic incremental backup trail.
+ * This replaces the auto-backup functionality with continuous, granular backups.
+ *
+ * Directory structure:
+ * ~/.config/ynab-mcp-deluxe/sync-history/[budgetId]/
+ *   - 20260125T143022Z-full.json    # Initial sync
+ *   - 20260125T153022Z-delta.json   # Delta sync
+ *   - ...
+ */
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Get the base sync history directory path.
+ * ~/.config/ynab-mcp-deluxe/sync-history/
+ */
+export function getSyncHistoryBaseDir() {
+    return join(homedir(), '.config', 'ynab-mcp-deluxe', 'sync-history');
+}
+/**
+ * Validate that a budgetId is safe to use in file paths.
+ * YNAB budget IDs are UUIDs (alphanumeric with hyphens).
+ * This prevents path traversal attacks with malicious budgetId values.
+ *
+ * @param budgetId - The budget ID to validate
+ * @returns true if the budgetId is safe for use in paths
+ */
+export function isValidBudgetIdForPath(budgetId) {
+    // YNAB budget IDs are UUIDs: alphanumeric characters and hyphens only
+    // Example: "12345678-1234-1234-1234-123456789abc"
+    // Reject empty strings, path separators, dots, and other special characters
+    return /^[a-zA-Z0-9-]+$/.test(budgetId) && budgetId.length > 0;
+}
+/**
+ * Get the sync history directory for a specific budget.
+ * ~/.config/ynab-mcp-deluxe/sync-history/[budgetId]/
+ *
+ * @param budgetId - The budget ID (must be a valid UUID format)
+ * @throws Error if budgetId contains invalid characters (path traversal protection)
+ */
+export function getSyncHistoryDir(budgetId) {
+    if (!isValidBudgetIdForPath(budgetId)) {
+        throw new Error(`Invalid budgetId for file path: "${budgetId}". Budget IDs must contain only alphanumeric characters and hyphens.`);
+    }
+    return join(getSyncHistoryBaseDir(), budgetId);
+}
+/**
+ * Ensure the sync history directory exists for a budget.
+ * Creates the directory tree if it doesn't exist.
+ */
+export async function ensureSyncHistoryDir(budgetId) {
+    const dir = getSyncHistoryDir(budgetId);
+    await mkdir(dir, { recursive: true });
+}
+/**
+ * Generate sync history filename with timestamp and sync type.
+ * Format: YYYYMMDDTHHMMSSZ-[full|delta].json
+ *
+ * Uses compact ISO 8601 format for easy sorting and readability.
+ * Example: 20260125T143022Z-full.json
+ */
+export function generateSyncFilename(syncType) {
+    const now = new Date();
+    // Format: 20260125T143022Z (compact ISO 8601 UTC)
+    const timestamp = now
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d+Z$/, 'Z');
+    return `${timestamp}-${syncType}.json`;
+}
+/**
+ * Persist a sync response to disk.
+ *
+ * This function is designed to be fail-safe: if the write fails,
+ * it logs a warning but does not throw. The sync operation should
+ * continue even if persistence fails.
+ *
+ * @param budgetId - The budget ID
+ * @param syncType - 'full' or 'delta'
+ * @param budget - The budget data from YNAB API
+ * @param serverKnowledge - The server_knowledge from this sync
+ * @param previousServerKnowledge - For delta syncs, the previous server_knowledge
+ * @param log - Logger for debug/error output
+ * @returns The file path if successful, null if failed
+ */
+export async function persistSyncResponse(budgetId, syncType, budget, serverKnowledge, previousServerKnowledge, log) {
+    const startTime = performance.now();
+    try {
+        // Ensure directory exists
+        await ensureSyncHistoryDir(budgetId);
+        // Build the sync history entry
+        const entry = {
+            budget,
+            previousServerKnowledge,
+            serverKnowledge,
+            syncType,
+            syncedAt: new Date().toISOString(),
+        };
+        // Generate filename and path
+        const filename = generateSyncFilename(syncType);
+        const filePath = join(getSyncHistoryDir(budgetId), filename);
+        // Write to disk
+        await writeFile(filePath, JSON.stringify(entry, null, 2), 'utf-8');
+        const durationMs = Math.round(performance.now() - startTime);
+        log.debug('Sync history persisted', {
+            budgetId,
+            durationMs,
+            filePath,
+            serverKnowledge,
+            syncType,
+        });
+        return filePath;
+    }
+    catch (error) {
+        // Log warning but don't fail - persistence is a safety feature, not critical path
+        const durationMs = Math.round(performance.now() - startTime);
+        log.warn('Failed to persist sync history (continuing with sync)', {
+            budgetId,
+            durationMs,
+            error: error instanceof Error ? error.message : String(error),
+            syncType,
+        });
+        return null;
+    }
+}
+/**
+ * Clear sync history for a specific budget or all budgets.
+ *
+ * @param budgetId - Optional budget ID to clear. If not provided, clears all budgets.
+ * @param log - Logger for debug/error output
+ * @returns Summary of the clear operation
+ */
+export async function clearSyncHistory(budgetId, log) {
+    const result = {
+        budgetsCleared: [],
+        errors: [],
+        filesDeleted: 0,
+    };
+    const baseDir = getSyncHistoryBaseDir();
+    try {
+        if (budgetId !== null) {
+            // Clear specific budget
+            const budgetDir = getSyncHistoryDir(budgetId);
+            try {
+                const files = await readdir(budgetDir);
+                result.filesDeleted = files.length;
+                await rm(budgetDir, { force: true, recursive: true });
+                result.budgetsCleared.push(budgetId);
+                log.info('Cleared sync history for budget', {
+                    budgetId,
+                    filesDeleted: result.filesDeleted,
+                });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Directory doesn't exist - nothing to clear
+                    log.info('No sync history to clear for budget', { budgetId });
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        else {
+            // Clear all budgets
+            try {
+                const budgetDirs = await readdir(baseDir);
+                for (const dir of budgetDirs) {
+                    const budgetDir = getSyncHistoryDir(dir);
+                    try {
+                        const files = await readdir(budgetDir);
+                        result.filesDeleted += files.length;
+                        await rm(budgetDir, { force: true, recursive: true });
+                        result.budgetsCleared.push(dir);
+                    }
+                    catch (dirError) {
+                        result.errors.push(`Failed to clear ${dir}: ${dirError instanceof Error ? dirError.message : String(dirError)}`);
+                    }
+                }
+                log.info('Cleared all sync history', {
+                    budgetsCleared: result.budgetsCleared.length,
+                    filesDeleted: result.filesDeleted,
+                });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Base directory doesn't exist - nothing to clear
+                    log.info('No sync history directory exists');
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        result.errors.push(errorMessage);
+        log.error('Failed to clear sync history', { budgetId, error: errorMessage });
+    }
+    return result;
+}

package/dist/sync-providers.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Sync providers for fetching budget data.
+ *
+ * SyncProvider is an abstraction that allows us to swap between:
+ * - ApiSyncProvider: Uses the YNAB API (production)
+ * - StaticSyncProvider: Loads from a JSON file (testing)
+ *
+ * This enables fast iteration and deterministic E2E tests.
+ */
+import type { SyncProvider } from './types.js';
+import type { BudgetDetail } from 'ynab';
+/**
+ * API-based sync provider that fetches from the YNAB API.
+ * This is the default provider for production use.
+ */
+export declare class ApiSyncProvider implements SyncProvider {
+    private api;
+    constructor(accessToken: string);
+    /**
+     * Perform a full sync - fetches the complete budget.
+     */
+    fullSync(budgetId: string): Promise<{
+        budget: BudgetDetail;
+        serverKnowledge: number;
+    }>;
+    /**
+     * Perform a delta sync - fetches only changes since lastKnowledge.
+     */
+    deltaSync(budgetId: string, lastKnowledge: number): Promise<{
+        budget: BudgetDetail;
+        serverKnowledge: number;
+    }>;
+}
+/**
+ * Static sync provider that loads from a JSON file.
+ * Used for testing to avoid hitting the YNAB API.
+ *
+ * Currently a stub - full implementation will be added later.
+ * See ROADMAP.md for "Static JSON Testing Mode" future enhancement.
+ */
+export declare class StaticSyncProvider implements SyncProvider {
+    private budgetData;
+    private serverKnowledge;
+    constructor(budgetData: BudgetDetail, serverKnowledge?: number);
+    /**
+     * Full sync returns the static budget data.
+     */
+    fullSync(_budgetId: string): Promise<{
+        budget: BudgetDetail;
+        serverKnowledge: number;
+    }>;
+    /**
+     * Delta sync returns empty changes (no changes since static data is immutable).
+     * In the future, this could return changes from a mutations overlay.
+     */
+    deltaSync(_budgetId: string, _lastKnowledge: number): Promise<{
+        budget: BudgetDetail;
+        serverKnowledge: number;
+    }>;
+}
+/**
+ * Create the appropriate sync provider based on environment.
+ *
+ * If YNAB_STATIC_BUDGET_FILE is set, loads from that file.
+ * Otherwise, uses the YNAB API with YNAB_ACCESS_TOKEN.
+ *
+ * @returns The configured SyncProvider
+ * @throws Error if required environment variables are missing
+ */
+export declare function createSyncProvider(): SyncProvider;
+//# sourceMappingURL=sync-providers.d.ts.map

package/dist/sync-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-providers.d.ts","sourceRoot":"","sources":["../src/sync-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,MAAM,CAAC;AAIvC;;;GAGG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,OAAO,CAAC,GAAG,CAAU;gBAET,WAAW,EAAE,MAAM;IAI/B;;OAEG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAC,CAAC;IAQ3D;;OAEG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAC,CAAC;CAU5D;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,UAAU,CAAe;IACjC,OAAO,CAAC,eAAe,CAAS;gBAEpB,UAAU,EAAE,YAAY,EAAE,eAAe,SAAI;IAKzD;;OAEG;IACH,QAAQ,CACN,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAC,CAAC;IAO3D;;;OAGG;IACH,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAC,CAAC;CAc5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAqBjD"}

package/dist/sync-providers.js

@@ -0,0 +1,105 @@
+/**
+ * Sync providers for fetching budget data.
+ *
+ * SyncProvider is an abstraction that allows us to swap between:
+ * - ApiSyncProvider: Uses the YNAB API (production)
+ * - StaticSyncProvider: Loads from a JSON file (testing)
+ *
+ * This enables fast iteration and deterministic E2E tests.
+ */
+import { api as YnabApi } from 'ynab';
+/**
+ * API-based sync provider that fetches from the YNAB API.
+ * This is the default provider for production use.
+ */
+export class ApiSyncProvider {
+    api;
+    constructor(accessToken) {
+        this.api = new YnabApi(accessToken);
+    }
+    /**
+     * Perform a full sync - fetches the complete budget.
+     */
+    async fullSync(budgetId) {
+        const response = await this.api.budgets.getBudgetById(budgetId);
+        return {
+            budget: response.data.budget,
+            serverKnowledge: response.data.server_knowledge,
+        };
+    }
+    /**
+     * Perform a delta sync - fetches only changes since lastKnowledge.
+     */
+    async deltaSync(budgetId, lastKnowledge) {
+        const response = await this.api.budgets.getBudgetById(budgetId, lastKnowledge);
+        return {
+            budget: response.data.budget,
+            serverKnowledge: response.data.server_knowledge,
+        };
+    }
+}
+/**
+ * Static sync provider that loads from a JSON file.
+ * Used for testing to avoid hitting the YNAB API.
+ *
+ * Currently a stub - full implementation will be added later.
+ * See ROADMAP.md for "Static JSON Testing Mode" future enhancement.
+ */
+export class StaticSyncProvider {
+    budgetData;
+    serverKnowledge;
+    constructor(budgetData, serverKnowledge = 1) {
+        this.budgetData = budgetData;
+        this.serverKnowledge = serverKnowledge;
+    }
+    /**
+     * Full sync returns the static budget data.
+     */
+    fullSync(_budgetId) {
+        return Promise.resolve({
+            budget: this.budgetData,
+            serverKnowledge: this.serverKnowledge,
+        });
+    }
+    /**
+     * Delta sync returns empty changes (no changes since static data is immutable).
+     * In the future, this could return changes from a mutations overlay.
+     */
+    deltaSync(_budgetId, _lastKnowledge) {
+        // Return an "empty" delta - same server knowledge, no changes
+        // The budget object will have empty/undefined arrays, indicating no changes
+        const emptyDelta = {
+            id: this.budgetData.id,
+            name: this.budgetData.name,
+            // All other fields are optional and undefined = no changes
+        };
+        return Promise.resolve({
+            budget: emptyDelta,
+            serverKnowledge: this.serverKnowledge,
+        });
+    }
+}
+/**
+ * Create the appropriate sync provider based on environment.
+ *
+ * If YNAB_STATIC_BUDGET_FILE is set, loads from that file.
+ * Otherwise, uses the YNAB API with YNAB_ACCESS_TOKEN.
+ *
+ * @returns The configured SyncProvider
+ * @throws Error if required environment variables are missing
+ */
+export function createSyncProvider() {
+    const staticBudgetFile = process.env['YNAB_STATIC_BUDGET_FILE'];
+    if (staticBudgetFile !== undefined && staticBudgetFile !== '') {
+        // Static mode - load from JSON file
+        // Note: Full implementation will be added in future enhancement
+        throw new Error(`Static budget file support not yet implemented. ` +
+            `Set YNAB_STATIC_BUDGET_FILE is set to: ${staticBudgetFile}`);
+    }
+    // API mode - use YNAB API
+    const accessToken = process.env['YNAB_ACCESS_TOKEN'];
+    if (accessToken === undefined || accessToken === '') {
+        throw new Error('YNAB authentication failed. Check that YNAB_ACCESS_TOKEN environment variable is set.');
+    }
+    return new ApiSyncProvider(accessToken);
+}