ynab-mcp-deluxe 0.1.9

package/dist/ynab-client.d.ts

@@ -0,0 +1,257 @@
+/**
+ * YNAB API client wrapper with caching and enrichment
+ */
+import type { AccountSelector, BudgetSelector, CategorySelector, CreateTransactionInput, EnrichedAccount, EnrichedBudgetMonthDetail, EnrichedBudgetSummary, EnrichedCategory, EnrichedMonthCategory, EnrichedMonthSummary, EnrichedPayee, EnrichedScheduledTransaction, EnrichedTransaction, GetLocalBudgetOptions, LocalBudget, PayeeSelector, TransactionUpdate } from './types.js';
+import { type AccountType, type CategoryGroupWithCategories, type CurrencyFormat } from 'ynab';
+/**
+ * Check if the server is running in read-only mode
+ */
+export declare function isReadOnlyMode(): boolean;
+/**
+ * Assert that write operations are allowed
+ * @throws Error if read-only mode is enabled
+ */
+export declare function assertWriteAllowed(operation: string): void;
+/**
+ * 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 declare function getSyncIntervalMs(): number;
+/**
+ * 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;
+}
+/**
+ * YNAB client with local budget sync
+ */
+declare class YnabClient {
+    private api;
+    private budgets;
+    private localBudgets;
+    /** Store previous full API responses for drift snapshot collection */
+    private previousBudgetDetails;
+    private lastUsedBudgetId;
+    private syncProvider;
+    /**
+     * Get the YNAB API instance, creating it if necessary
+     */
+    private getApi;
+    /**
+     * Get the sync provider, creating it if necessary
+     */
+    private getSyncProvider;
+    /**
+     * Determine what kind of sync is needed based on policy.
+     * Returns both the sync type and the reason for logging.
+     */
+    private determineSyncNeeded;
+    /**
+     * 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
+     */
+    getLocalBudgetWithSync(budgetId: string, options?: GetLocalBudgetOptions, contextLog?: ContextLog): Promise<LocalBudget>;
+    /**
+     * Mark a budget as needing sync (called after write operations).
+     * The next read operation will trigger a delta sync.
+     */
+    markNeedsSync(budgetId: string): void;
+    /**
+     * Get all budgets
+     */
+    getBudgets(): Promise<EnrichedBudgetSummary[]>;
+    /**
+     * 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.
+     */
+    resolveBudgetId(selector?: BudgetSelector): Promise<string>;
+    /**
+     * 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.
+     */
+    private getLocalBudget;
+    /**
+     * 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.
+     */
+    private buildCategoryGroupsWithCategories;
+    /**
+     * Convert milliunits to currency amount
+     */
+    private toCurrency;
+    /**
+     * 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[].
+     */
+    private enrichTransaction;
+    /**
+     * 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
+     */
+    private enrichTransactionSummary;
+    /**
+     * 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.
+     */
+    getTransactions(budgetId: string, options?: {
+        accountId?: string;
+        sinceDate?: string;
+        type?: 'uncategorized' | 'unapproved';
+    }): Promise<EnrichedTransaction[]>;
+    /**
+     * Resolve an account selector to an account ID
+     */
+    resolveAccountId(budgetId: string, selector: AccountSelector): Promise<string>;
+    /**
+     * Get all accounts for a budget
+     */
+    getAccounts(budgetId: string, includeClosed?: boolean): Promise<EnrichedAccount[]>;
+    /**
+     * Get all categories for a budget
+     */
+    getCategories(budgetId: string, includeHidden?: boolean): Promise<{
+        flat: EnrichedCategory[];
+        groups: CategoryGroupWithCategories[];
+    }>;
+    /**
+     * Get all payees for a budget
+     */
+    getPayees(budgetId: string): Promise<EnrichedPayee[]>;
+    /**
+     * Update multiple transactions using the bulk PATCH endpoint
+     */
+    updateTransactions(budgetId: string, updates: TransactionUpdate[]): Promise<{
+        updated: EnrichedTransaction[];
+    }>;
+    /**
+     * Get currency format for a budget
+     */
+    getCurrencyFormat(budgetId: string): Promise<CurrencyFormat | null>;
+    /**
+     * Get budget info (name, id) for journaling
+     */
+    getBudgetInfo(budgetId: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * 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)
+     */
+    getBudgetByIdRaw(budgetId: string): Promise<{
+        budget: unknown;
+        server_knowledge: number;
+    }>;
+    /**
+     * Resolve a category selector to a category ID
+     */
+    resolveCategoryId(budgetId: string, selector: CategorySelector): Promise<string>;
+    /**
+     * Resolve a payee selector to a payee ID
+     */
+    resolvePayeeId(budgetId: string, selector: PayeeSelector): Promise<string | null>;
+    /**
+     * Get a single transaction by ID.
+     *
+     * Reads from LocalBudget.transactions - no API call is made.
+     */
+    getTransaction(budgetId: string, transactionId: string): Promise<EnrichedTransaction>;
+    /**
+     * Get scheduled transactions.
+     *
+     * Reads from LocalBudget.scheduledTransactions - no API call is made.
+     */
+    getScheduledTransactions(budgetId: string): Promise<EnrichedScheduledTransaction[]>;
+    /**
+     * Get budget months list.
+     *
+     * Reads from LocalBudget.months - no API call is made.
+     */
+    getBudgetMonths(budgetId: string): Promise<EnrichedMonthSummary[]>;
+    /**
+     * Get budget month detail with categories.
+     *
+     * Reads from LocalBudget.months - no API call is made.
+     */
+    getBudgetMonth(budgetId: string, month: string): Promise<EnrichedBudgetMonthDetail>;
+    /**
+     * Create one or more transactions
+     */
+    createTransactions(budgetId: string, transactions: CreateTransactionInput[]): Promise<{
+        created: EnrichedTransaction[];
+        duplicates: string[];
+    }>;
+    /**
+     * Delete a transaction
+     */
+    deleteTransaction(budgetId: string, transactionId: string): Promise<{
+        deleted: EnrichedTransaction;
+    }>;
+    /**
+     * Import transactions from linked accounts
+     */
+    importTransactions(budgetId: string): Promise<{
+        imported_count: number;
+        transaction_ids: string[];
+    }>;
+    /**
+     * Create a new account
+     */
+    createAccount(budgetId: string, name: string, type: AccountType, balance: number): Promise<EnrichedAccount>;
+    /**
+     * Update category budget for a month
+     */
+    updateCategoryBudget(budgetId: string, month: string, categoryId: string, budgeted: number): Promise<EnrichedMonthCategory>;
+    /**
+     * Clear all local budgets (useful for testing or forcing full re-sync)
+     */
+    clearLocalBudgets(): void;
+    /**
+     * 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?: string): void;
+}
+export declare const ynabClient: YnabClient;
+export {};
+//# sourceMappingURL=ynab-client.d.ts.map

package/dist/ynab-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ynab-client.d.ts","sourceRoot":"","sources":["../src/ynab-client.ts"],"names":[],"mappings":"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"}