@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/server/budgetResolver.d.ts

@@ -0,0 +1,15 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare class BudgetResolver {
+    private static readonly UUID_REGEX;
+    private static readonly ALLOWED_KEYWORDS;
+    static resolveBudgetId(providedId?: string, defaultId?: string): string | CallToolResult;
+    static validateBudgetId(budgetId: string): string | CallToolResult;
+    static createMissingBudgetError(): CallToolResult;
+    static createInvalidBudgetError(details: string): CallToolResult;
+    static resolveBudgetIdOrThrow(providedId?: string, defaultId?: string): string;
+    static validateBudgetIdOrThrow(budgetId: string): string;
+}
+export declare function resolveBudgetId(providedId?: string, defaultId?: string): string | CallToolResult;
+export declare function validateBudgetId(budgetId: string): string | CallToolResult;
+export declare function createMissingBudgetError(): CallToolResult;
+export declare function createInvalidBudgetError(details: string): CallToolResult;

package/dist/server/budgetResolver.js

@@ -0,0 +1,99 @@
+import { ErrorHandler } from './errorHandler.js';
+export class BudgetResolver {
+    static resolveBudgetId(providedId, defaultId) {
+        if (providedId !== undefined && providedId !== null) {
+            const trimmed = providedId.trim();
+            if (trimmed === 'default') {
+                if (defaultId) {
+                    return this.validateBudgetId(defaultId);
+                }
+                return this.createMissingBudgetError();
+            }
+            if (trimmed === 'last-used') {
+                return ErrorHandler.createValidationError('Unsupported keyword', 'The "last-used" keyword is not supported yet. Please use a specific budget ID or set a default budget.', [
+                    'Use a specific budget ID (UUID format)',
+                    'Set a default budget using the set_default_budget tool',
+                    'Use the "default" keyword after setting a default budget',
+                    'Run the list_budgets tool to see available budget IDs',
+                ]);
+            }
+            return this.validateBudgetId(providedId);
+        }
+        if (defaultId) {
+            return this.validateBudgetId(defaultId);
+        }
+        return this.createMissingBudgetError();
+    }
+    static validateBudgetId(budgetId) {
+        if (!budgetId || typeof budgetId !== 'string') {
+            return this.createInvalidBudgetError('Budget ID must be provided as a non-empty string');
+        }
+        const trimmed = budgetId.trim();
+        if (!trimmed) {
+            return this.createInvalidBudgetError('Budget ID cannot be empty or whitespace only');
+        }
+        if (process.env['NODE_ENV'] === 'test') {
+            const testIdentifierPattern = /^(test|budget|account|category|transaction|payee|mock)-[a-z0-9_-]+$/i;
+            if (testIdentifierPattern.test(trimmed)) {
+                return trimmed;
+            }
+        }
+        if (!this.UUID_REGEX.test(trimmed)) {
+            return this.createInvalidBudgetError(`Invalid budget ID format: '${trimmed}'. Must be a valid UUID format (versions 1-5)`);
+        }
+        return trimmed;
+    }
+    static createMissingBudgetError() {
+        const detailMessage = `A budget ID is required for this operation. You can either:
+1. Provide a specific budget_id parameter
+2. Set a default budget using the set_default_budget tool first`;
+        return ErrorHandler.createValidationError('No budget ID provided and no default budget set', detailMessage, [
+            'Set a default budget first using the set_default_budget tool',
+            'Provide a budget_id parameter when invoking the tool',
+        ]);
+    }
+    static createInvalidBudgetError(details) {
+        const detailMessage = `${details}
+
+Valid formats:
+- UUID format (versions 1-5, e.g., "123e4567-e89b-12d3-a456-426614174000")
+- Special keywords: ${this.ALLOWED_KEYWORDS.map((k) => `"${k}"`).join(', ')}
+
+You can use the list_budgets tool to see available budget IDs.`;
+        return ErrorHandler.createValidationError('Invalid budget ID format', detailMessage, [
+            'Use a valid UUID format (UUID v1-v5, e.g., 123e4567-e89b-12d3-a456-426614174000; standard UUID v4 format works as well)',
+            'Run the list_budgets tool to view available budget IDs',
+            'Use the special keyword "default" for convenience',
+        ]);
+    }
+    static resolveBudgetIdOrThrow(providedId, defaultId) {
+        const result = this.resolveBudgetId(providedId, defaultId);
+        if (typeof result === 'string') {
+            return result;
+        }
+        const errorText = result.content?.[0]?.type === 'text' ? result.content[0].text : 'Budget resolution failed';
+        throw new Error(errorText);
+    }
+    static validateBudgetIdOrThrow(budgetId) {
+        const result = this.validateBudgetId(budgetId);
+        if (typeof result === 'string') {
+            return result;
+        }
+        const errorText = result.content?.[0]?.type === 'text' ? result.content[0].text : 'Budget validation failed';
+        throw new Error(errorText);
+    }
+}
+BudgetResolver.UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+BudgetResolver.ALLOWED_KEYWORDS = ['default'];
+export function resolveBudgetId(providedId, defaultId) {
+    return BudgetResolver.resolveBudgetId(providedId, defaultId);
+}
+export function validateBudgetId(budgetId) {
+    return BudgetResolver.validateBudgetId(budgetId);
+}
+export function createMissingBudgetError() {
+    return BudgetResolver.createMissingBudgetError();
+}
+export function createInvalidBudgetError(details) {
+    return BudgetResolver.createInvalidBudgetError(details);
+}

package/dist/server/cacheManager.d.ts

@@ -0,0 +1,74 @@
+interface CacheEntry<T> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+    staleWhileRevalidate?: number;
+}
+interface CacheSetOptions {
+    ttl?: number;
+    staleWhileRevalidate?: number;
+}
+export declare class CacheManager {
+    private cache;
+    private readonly defaultTTL;
+    private hits;
+    private misses;
+    private evictions;
+    private lastCleanup;
+    private maxEntries;
+    private defaultStaleWindow;
+    private pendingFetches;
+    private pendingRefresh;
+    constructor();
+    get<T>(key: string): T | null;
+    has(key: string): boolean;
+    set<T>(key: string, data: T, ttlOrOptions?: number | CacheSetOptions): void;
+    delete(key: string): boolean;
+    deleteMany(keys: Iterable<string>): void;
+    deleteByPrefix(prefix: string): number;
+    deleteByBudgetId(budgetId: string): number;
+    getKeys(): string[];
+    clear(): void;
+    getStats(): {
+        size: number;
+        keys: string[];
+        hits: number;
+        misses: number;
+        evictions: number;
+        lastCleanup: number | null;
+        maxEntries: number;
+        hitRate: number;
+    };
+    getEntriesForSizeEstimation(): [string, CacheEntry<unknown>][];
+    getCacheMetadata(): {
+        key: string;
+        timestamp: number;
+        ttl: number;
+        staleWhileRevalidate?: number;
+        dataType: string;
+        isExpired: boolean;
+    }[];
+    cleanup(): number;
+    cleanupDetailed(): {
+        cleaned: number;
+        evictions: number;
+    };
+    wrap<T>(key: string, options: CacheSetOptions & {
+        loader: () => Promise<T>;
+    }): Promise<T>;
+    private evictIfNeeded;
+    private parseEnvInt;
+    static generateKey(prefix: string, ...params: (string | number | boolean | undefined)[]): string;
+}
+export declare const CACHE_TTLS: {
+    readonly BUDGETS: number;
+    readonly ACCOUNTS: number;
+    readonly CATEGORIES: number;
+    readonly PAYEES: number;
+    readonly TRANSACTIONS: number;
+    readonly SCHEDULED_TRANSACTIONS: number;
+    readonly USER_INFO: number;
+    readonly MONTHS: number;
+};
+export declare const cacheManager: CacheManager;
+export {};

package/dist/server/cacheManager.js

@@ -0,0 +1,306 @@
+export class CacheManager {
+    constructor() {
+        this.cache = new Map();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+        this.lastCleanup = null;
+        this.pendingFetches = new Map();
+        this.pendingRefresh = new Set();
+        this.maxEntries = this.parseEnvInt('YNAB_MCP_CACHE_MAX_ENTRIES', 1000);
+        this.defaultStaleWindow = this.parseEnvInt('YNAB_MCP_CACHE_STALE_MS', 2 * 60 * 1000);
+        this.defaultTTL = this.parseEnvInt('YNAB_MCP_CACHE_DEFAULT_TTL_MS', 300000);
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return null;
+        }
+        const now = Date.now();
+        const age = now - entry.timestamp;
+        if (age > entry.ttl) {
+            const staleWindow = entry.staleWhileRevalidate || 0;
+            if (staleWindow > 0 && age <= entry.ttl + staleWindow) {
+                this.hits++;
+                this.cache.delete(key);
+                this.cache.set(key, entry);
+                this.pendingRefresh.add(key);
+                return entry.data;
+            }
+            this.cache.delete(key);
+            this.pendingFetches.delete(key);
+            this.pendingRefresh.delete(key);
+            this.misses++;
+            return null;
+        }
+        this.hits++;
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.data;
+    }
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        const now = Date.now();
+        const age = now - entry.timestamp;
+        if (age > entry.ttl) {
+            const staleWindow = entry.staleWhileRevalidate || 0;
+            if (staleWindow > 0 && age <= entry.ttl + staleWindow) {
+                return true;
+            }
+            this.cache.delete(key);
+            this.pendingFetches.delete(key);
+            this.pendingRefresh.delete(key);
+            return false;
+        }
+        return true;
+    }
+    set(key, data, ttlOrOptions) {
+        if (this.maxEntries <= 0) {
+            return;
+        }
+        const isUpdate = this.cache.has(key);
+        if (!isUpdate) {
+            this.evictIfNeeded();
+        }
+        let ttl;
+        let staleWhileRevalidate;
+        if (typeof ttlOrOptions === 'number') {
+            ttl = Number.isFinite(ttlOrOptions) ? ttlOrOptions : this.defaultTTL;
+            staleWhileRevalidate = undefined;
+        }
+        else if (ttlOrOptions === undefined) {
+            ttl = this.defaultTTL;
+            staleWhileRevalidate = undefined;
+        }
+        else {
+            const providedTtl = ttlOrOptions?.ttl;
+            ttl = providedTtl !== undefined ? providedTtl : this.defaultTTL;
+            if (ttlOrOptions && 'staleWhileRevalidate' in ttlOrOptions) {
+                staleWhileRevalidate = ttlOrOptions.staleWhileRevalidate;
+            }
+            else {
+                staleWhileRevalidate = ttlOrOptions?.staleWhileRevalidate;
+            }
+            if (staleWhileRevalidate === undefined && this.defaultStaleWindow > 0) {
+                staleWhileRevalidate = this.defaultStaleWindow;
+            }
+        }
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            ttl,
+        };
+        if (staleWhileRevalidate !== undefined) {
+            entry.staleWhileRevalidate = staleWhileRevalidate;
+        }
+        if (isUpdate) {
+            this.cache.delete(key);
+        }
+        this.cache.set(key, entry);
+        this.pendingFetches.delete(key);
+        this.pendingRefresh.delete(key);
+    }
+    delete(key) {
+        const deleted = this.cache.delete(key);
+        if (deleted) {
+            this.pendingFetches.delete(key);
+            this.pendingRefresh.delete(key);
+        }
+        return deleted;
+    }
+    deleteMany(keys) {
+        for (const key of keys) {
+            this.cache.delete(key);
+            this.pendingFetches.delete(key);
+            this.pendingRefresh.delete(key);
+        }
+    }
+    deleteByPrefix(prefix) {
+        if (!prefix) {
+            return 0;
+        }
+        const normalizedPrefix = prefix.endsWith(':') ? prefix.slice(0, -1) : prefix;
+        const prefixWithColon = `${normalizedPrefix}:`;
+        let removed = 0;
+        for (const key of this.cache.keys()) {
+            if (key === normalizedPrefix || key.startsWith(prefixWithColon)) {
+                this.cache.delete(key);
+                this.pendingFetches.delete(key);
+                this.pendingRefresh.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    deleteByBudgetId(budgetId) {
+        if (!budgetId) {
+            return 0;
+        }
+        let removed = 0;
+        for (const key of this.cache.keys()) {
+            const segments = key.split(':');
+            if (segments.some((segment) => segment === budgetId)) {
+                this.cache.delete(key);
+                this.pendingFetches.delete(key);
+                this.pendingRefresh.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    getKeys() {
+        return Array.from(this.cache.keys());
+    }
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+        this.lastCleanup = null;
+        this.pendingFetches.clear();
+        this.pendingRefresh.clear();
+    }
+    getStats() {
+        const totalRequests = this.hits + this.misses;
+        return {
+            size: this.cache.size,
+            keys: Array.from(this.cache.keys()),
+            hits: this.hits,
+            misses: this.misses,
+            evictions: this.evictions,
+            lastCleanup: this.lastCleanup,
+            maxEntries: this.maxEntries,
+            hitRate: totalRequests > 0 ? this.hits / totalRequests : 0,
+        };
+    }
+    getEntriesForSizeEstimation() {
+        const now = Date.now();
+        return Array.from(this.cache.entries()).filter(([, entry]) => now - entry.timestamp <= entry.ttl);
+    }
+    getCacheMetadata() {
+        const now = Date.now();
+        return Array.from(this.cache.entries()).map(([key, entry]) => {
+            const metadata = {
+                key,
+                timestamp: entry.timestamp,
+                ttl: entry.ttl,
+                dataType: typeof entry.data,
+                isExpired: now - entry.timestamp > entry.ttl,
+            };
+            if (entry.staleWhileRevalidate !== undefined) {
+                metadata.staleWhileRevalidate = entry.staleWhileRevalidate;
+            }
+            return metadata;
+        });
+    }
+    cleanup() {
+        const result = this.cleanupDetailed();
+        return result.cleaned;
+    }
+    cleanupDetailed() {
+        const now = Date.now();
+        let cleaned = 0;
+        const initialEvictions = this.evictions;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > entry.ttl) {
+                this.cache.delete(key);
+                this.pendingFetches.delete(key);
+                this.pendingRefresh.delete(key);
+                cleaned++;
+                this.evictions++;
+            }
+        }
+        this.lastCleanup = now;
+        return { cleaned, evictions: this.evictions - initialEvictions };
+    }
+    async wrap(key, options) {
+        const existingEntry = this.cache.get(key);
+        const cached = this.get(key);
+        if (cached !== null) {
+            if (this.pendingRefresh.has(key) && !this.pendingFetches.has(key)) {
+                const refreshPromise = options.loader().then((result) => {
+                    const refreshOptions = {};
+                    const ttl = options.ttl ?? existingEntry?.ttl;
+                    if (ttl !== undefined) {
+                        refreshOptions.ttl = ttl;
+                    }
+                    const staleWhileRevalidate = options.staleWhileRevalidate ?? existingEntry?.staleWhileRevalidate;
+                    if (staleWhileRevalidate !== undefined) {
+                        refreshOptions.staleWhileRevalidate = staleWhileRevalidate;
+                    }
+                    this.set(key, result, refreshOptions);
+                    this.pendingFetches.delete(key);
+                    this.pendingRefresh.delete(key);
+                    return result;
+                }, (error) => {
+                    this.pendingFetches.delete(key);
+                    this.pendingRefresh.delete(key);
+                    throw error;
+                });
+                this.pendingFetches.set(key, refreshPromise);
+            }
+            return cached;
+        }
+        const existingFetch = this.pendingFetches.get(key);
+        if (existingFetch) {
+            return existingFetch;
+        }
+        const fetchPromise = options.loader().then((result) => {
+            this.set(key, result, options);
+            this.pendingFetches.delete(key);
+            this.pendingRefresh.delete(key);
+            return result;
+        }, (error) => {
+            this.pendingFetches.delete(key);
+            this.pendingRefresh.delete(key);
+            throw error;
+        });
+        this.pendingFetches.set(key, fetchPromise);
+        return fetchPromise;
+    }
+    evictIfNeeded() {
+        if (this.maxEntries <= 0)
+            return;
+        while (this.cache.size >= this.maxEntries) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+                this.pendingFetches.delete(firstKey);
+                this.pendingRefresh.delete(firstKey);
+                this.evictions++;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    parseEnvInt(key, defaultValue) {
+        const value = process.env[key];
+        if (!value)
+            return defaultValue;
+        const parsed = parseInt(value, 10);
+        return isNaN(parsed) ? defaultValue : parsed;
+    }
+    static generateKey(prefix, ...params) {
+        const cleanParams = params
+            .filter((p) => p !== undefined)
+            .map((p) => String(p))
+            .join(':');
+        return `${prefix}:${cleanParams}`;
+    }
+}
+export const CACHE_TTLS = {
+    BUDGETS: 10 * 60 * 1000,
+    ACCOUNTS: 5 * 60 * 1000,
+    CATEGORIES: 5 * 60 * 1000,
+    PAYEES: 10 * 60 * 1000,
+    TRANSACTIONS: 2 * 60 * 1000,
+    SCHEDULED_TRANSACTIONS: 5 * 60 * 1000,
+    USER_INFO: 30 * 60 * 1000,
+    MONTHS: 5 * 60 * 1000,
+};
+export const cacheManager = new CacheManager();

package/dist/server/config.d.ts

@@ -0,0 +1,3 @@
+import { ServerConfig } from '../types/index.js';
+export declare function validateEnvironment(): ServerConfig;
+export type { ServerConfig } from '../types/index.js';

package/dist/server/config.js

@@ -0,0 +1,19 @@
+import { ConfigurationError } from '../types/index.js';
+export function validateEnvironment() {
+    const accessToken = process.env['YNAB_ACCESS_TOKEN'];
+    const defaultBudgetId = process.env['YNAB_DEFAULT_BUDGET_ID'];
+    if (accessToken === undefined) {
+        throw new ConfigurationError('YNAB_ACCESS_TOKEN environment variable is required but not set');
+    }
+    if (typeof accessToken !== 'string' || accessToken.trim().length === 0) {
+        throw new ConfigurationError('YNAB_ACCESS_TOKEN must be a non-empty string');
+    }
+    const trimmedDefaultBudgetId = defaultBudgetId?.trim();
+    const config = {
+        accessToken: accessToken.trim(),
+    };
+    if (trimmedDefaultBudgetId && trimmedDefaultBudgetId.length > 0) {
+        config.defaultBudgetId = trimmedDefaultBudgetId;
+    }
+    return config;
+}

package/dist/server/deltaCache.d.ts

@@ -0,0 +1,61 @@
+import { CacheManager } from './cacheManager.js';
+import { ServerKnowledgeStore } from './serverKnowledgeStore.js';
+export interface Logger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export interface MergeOptions {
+    preserveDeleted?: boolean;
+    equalityFn?: (a: unknown, b: unknown) => boolean;
+}
+export type MergeFn<T> = (snapshot: T[], delta: T[], options?: MergeOptions) => T[];
+export interface DeltaFetchResult<T> {
+    data: T[];
+    wasCached: boolean;
+    usedDelta: boolean;
+    serverKnowledge: number;
+}
+export interface DeltaCacheEntry<T> {
+    snapshot: T[];
+    serverKnowledge: number;
+    timestamp: number;
+    ttl: number;
+    staleWhileRevalidate?: number;
+}
+export interface DeltaCacheStats {
+    deltaHits: number;
+    deltaMisses: number;
+    mergeOperations: number;
+    knowledgeGapEvents: number;
+}
+type DeltaFetcher<T> = (lastKnowledge?: number) => Promise<{
+    data: T[];
+    serverKnowledge: number;
+}>;
+export declare class DeltaCache {
+    private readonly cacheManager;
+    private readonly knowledgeStore;
+    private readonly logger;
+    private deltaHits;
+    private deltaMisses;
+    private mergeOperations;
+    private knowledgeGapEvents;
+    constructor(cacheManager: CacheManager, knowledgeStore: ServerKnowledgeStore, logger?: Logger);
+    fetchWithDelta<T extends {
+        deleted?: boolean;
+    }>(cacheKey: string, budgetId: string, fetcher: DeltaFetcher<T>, merger: MergeFn<T>, options: {
+        ttl: number;
+        forceFullRefresh?: boolean;
+        mergeOptions?: MergeOptions;
+        staleWhileRevalidate?: number;
+    }): Promise<DeltaFetchResult<T>>;
+    getStats(): DeltaCacheStats;
+    invalidate(budgetId: string, resourceType?: string): void;
+    forceFullRefresh(budgetId?: string, resourceType?: string): void;
+    private fetchWithoutDelta;
+    private filterDeleted;
+    private assertFiniteTtl;
+    private isDeltaEnabled;
+}
+export {};