@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/dist/tools/transactionReadTools.js

@@ -0,0 +1,202 @@
+import { CACHE_TTLS, CacheManager, cacheManager, } from "../server/cacheManager.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import { withToolErrorHandling } from "../types/index.js";
+import { milliunitsToAmount } from "../utils/amountUtils.js";
+import { createAdapters, createBudgetResolver } from "./adapters.js";
+import { resolveDeltaFetcherArgs } from "./deltaSupport.js";
+import { ExportTransactionsSchema, handleExportTransactions, } from "./exportTransactions.js";
+import { ToolAnnotationPresets } from "./toolCategories.js";
+import { GetTransactionSchema, ListTransactionsSchema, } from "./transactionSchemas.js";
+import { ensureTransaction, handleTransactionError, } from "./transactionUtils.js";
+export async function handleListTransactions(ynabAPI, deltaFetcherOrParams, maybeParams, errorHandler) {
+    const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
+    return await withToolErrorHandling(async () => {
+        let transactions;
+        let cacheHit = false;
+        let usedDelta = false;
+        if (params.account_id) {
+            const accountsResult = await deltaFetcher.fetchAccounts(params.budget_id);
+            const accountExists = accountsResult.data.some((account) => account.id === params.account_id);
+            if (!accountExists) {
+                throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
+            }
+            const result = await deltaFetcher.fetchTransactionsByAccount(params.budget_id, params.account_id, params.since_date);
+            transactions = result.data;
+            cacheHit = result.wasCached;
+            usedDelta = result.usedDelta;
+        }
+        else if (params.category_id) {
+            const response = await ynabAPI.transactions.getTransactionsByCategory(params.budget_id, params.category_id, params.since_date);
+            transactions = response.data.transactions;
+        }
+        else {
+            const result = await deltaFetcher.fetchTransactions(params.budget_id, params.since_date, params.type);
+            transactions = result.data;
+            cacheHit = result.wasCached;
+            usedDelta = result.usedDelta;
+        }
+        const estimatedSize = JSON.stringify(transactions).length;
+        const sizeLimit = 90000;
+        if (estimatedSize > sizeLimit) {
+            const preview = transactions.slice(0, 50);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: responseFormatter.format({
+                            message: `Found ${transactions.length} transactions (${Math.round(estimatedSize / 1024)}KB). Too large to display all.`,
+                            suggestion: "Use 'export_transactions' tool to save all transactions to a file.",
+                            showing: `First ${preview.length} transactions:`,
+                            total_count: transactions.length,
+                            estimated_size_kb: Math.round(estimatedSize / 1024),
+                            cached: cacheHit,
+                            cache_info: cacheHit
+                                ? `Data retrieved from cache for improved performance${usedDelta ? " (delta merge applied)" : ""}`
+                                : "Fresh data retrieved from YNAB API",
+                            preview_transactions: preview.map((transaction) => ({
+                                id: transaction.id,
+                                date: transaction.date,
+                                amount: milliunitsToAmount(transaction.amount),
+                                memo: transaction.memo,
+                                payee_name: transaction.payee_name,
+                                category_name: transaction.category_name,
+                            })),
+                        }),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: responseFormatter.format({
+                        total_count: transactions.length,
+                        cached: cacheHit,
+                        cache_info: cacheHit
+                            ? `Data retrieved from cache for improved performance${usedDelta ? " (delta merge applied)" : ""}`
+                            : "Fresh data retrieved from YNAB API",
+                        transactions: transactions.map((transaction) => ({
+                            id: transaction.id,
+                            date: transaction.date,
+                            amount: milliunitsToAmount(transaction.amount),
+                            memo: transaction.memo,
+                            cleared: transaction.cleared,
+                            approved: transaction.approved,
+                            flag_color: transaction.flag_color,
+                            account_id: transaction.account_id,
+                            payee_id: transaction.payee_id,
+                            category_id: transaction.category_id,
+                            transfer_account_id: transaction.transfer_account_id,
+                            transfer_transaction_id: transaction.transfer_transaction_id,
+                            matched_transaction_id: transaction.matched_transaction_id,
+                            import_id: transaction.import_id,
+                            deleted: transaction.deleted,
+                        })),
+                    }),
+                },
+            ],
+        };
+    }, "ynab:list_transactions", "listing transactions", errorHandler);
+}
+export async function handleGetTransaction(ynabAPI, params, _errorHandler) {
+    try {
+        const useCache = process.env["NODE_ENV"] !== "test";
+        let transaction;
+        let cacheHit = false;
+        if (useCache) {
+            const cacheKey = CacheManager.generateKey("transaction", "get", params.budget_id, params.transaction_id);
+            cacheHit = cacheManager.has(cacheKey);
+            transaction = await cacheManager.wrap(cacheKey, {
+                ttl: CACHE_TTLS.TRANSACTIONS,
+                loader: async () => {
+                    const response = await ynabAPI.transactions.getTransactionById(params.budget_id, params.transaction_id);
+                    return ensureTransaction(response.data.transaction, "Transaction not found");
+                },
+            });
+        }
+        else {
+            const response = await ynabAPI.transactions.getTransactionById(params.budget_id, params.transaction_id);
+            transaction = ensureTransaction(response.data.transaction, "Transaction not found");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: responseFormatter.format({
+                        transaction: {
+                            id: transaction.id,
+                            date: transaction.date,
+                            amount: milliunitsToAmount(transaction.amount),
+                            memo: transaction.memo,
+                            cleared: transaction.cleared,
+                            approved: transaction.approved,
+                            flag_color: transaction.flag_color,
+                            account_id: transaction.account_id,
+                            payee_id: transaction.payee_id,
+                            category_id: transaction.category_id,
+                            transfer_account_id: transaction.transfer_account_id,
+                            transfer_transaction_id: transaction.transfer_transaction_id,
+                            matched_transaction_id: transaction.matched_transaction_id,
+                            import_id: transaction.import_id,
+                            deleted: transaction.deleted,
+                            account_name: transaction.account_name,
+                            payee_name: transaction.payee_name,
+                            category_name: transaction.category_name,
+                        },
+                        cached: cacheHit,
+                        cache_info: cacheHit
+                            ? "Data retrieved from cache for improved performance"
+                            : "Fresh data retrieved from YNAB API",
+                    }),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleTransactionError(error, "Failed to get transaction");
+    }
+}
+export function registerTransactionReadTools(registry, context) {
+    const { adapt, adaptWithDelta } = createAdapters(context);
+    const budgetResolver = createBudgetResolver(context);
+    registry.register({
+        name: "list_transactions",
+        description: "List transactions for a budget with optional filtering",
+        inputSchema: ListTransactionsSchema,
+        handler: adaptWithDelta(handleListTransactions),
+        defaultArgumentResolver: budgetResolver(),
+        metadata: {
+            annotations: {
+                ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+                title: "YNAB: List Transactions",
+            },
+        },
+    });
+    registry.register({
+        name: "export_transactions",
+        description: "Export all transactions to a JSON file with descriptive filename",
+        inputSchema: ExportTransactionsSchema,
+        handler: adapt(handleExportTransactions),
+        defaultArgumentResolver: budgetResolver(),
+        metadata: {
+            annotations: {
+                ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+                title: "YNAB: Export Transactions",
+            },
+        },
+    });
+    registry.register({
+        name: "get_transaction",
+        description: "Get detailed information for a specific transaction",
+        inputSchema: GetTransactionSchema,
+        handler: adapt(handleGetTransaction),
+        defaultArgumentResolver: budgetResolver(),
+        metadata: {
+            annotations: {
+                ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+                title: "YNAB: Get Transaction Details",
+            },
+        },
+    });
+}

package/dist/tools/transactionSchemas.d.ts

@@ -0,0 +1,309 @@
+import type * as ynab from "ynab";
+import { z } from "zod/v4";
+export declare const ListTransactionsSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    account_id: z.ZodOptional<z.ZodString>;
+    category_id: z.ZodOptional<z.ZodString>;
+    since_date: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        uncategorized: "uncategorized";
+        unapproved: "unapproved";
+    }>>;
+}, z.core.$strict>;
+export type ListTransactionsParams = z.infer<typeof ListTransactionsSchema>;
+export declare const GetTransactionSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    transaction_id: z.ZodString;
+}, z.core.$strict>;
+export type GetTransactionParams = z.infer<typeof GetTransactionSchema>;
+export declare const CreateTransactionSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    account_id: z.ZodString;
+    amount: z.ZodNumber;
+    date: z.ZodString;
+    payee_name: z.ZodOptional<z.ZodString>;
+    payee_id: z.ZodOptional<z.ZodString>;
+    category_id: z.ZodOptional<z.ZodString>;
+    memo: z.ZodOptional<z.ZodString>;
+    cleared: z.ZodOptional<z.ZodEnum<{
+        cleared: "cleared";
+        uncleared: "uncleared";
+        reconciled: "reconciled";
+    }>>;
+    approved: z.ZodOptional<z.ZodBoolean>;
+    flag_color: z.ZodOptional<z.ZodEnum<{
+        red: "red";
+        orange: "orange";
+        yellow: "yellow";
+        green: "green";
+        blue: "blue";
+        purple: "purple";
+    }>>;
+    import_id: z.ZodOptional<z.ZodString>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+    subtransactions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        amount: z.ZodNumber;
+        payee_name: z.ZodOptional<z.ZodString>;
+        payee_id: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodString>;
+        memo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type CreateTransactionParams = z.infer<typeof CreateTransactionSchema>;
+export interface SubtransactionInput {
+    amount: number;
+    payee_name?: string;
+    payee_id?: string;
+    category_id?: string;
+    memo?: string;
+}
+export type BulkTransactionInput = Omit<CreateTransactionParams, "budget_id" | "dry_run" | "subtransactions">;
+export declare const CreateTransactionsSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    transactions: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        cleared: z.ZodOptional<z.ZodEnum<{
+            cleared: "cleared";
+            uncleared: "uncleared";
+            reconciled: "reconciled";
+        }>>;
+        amount: z.ZodNumber;
+        memo: z.ZodOptional<z.ZodString>;
+        approved: z.ZodOptional<z.ZodBoolean>;
+        flag_color: z.ZodOptional<z.ZodEnum<{
+            red: "red";
+            orange: "orange";
+            yellow: "yellow";
+            green: "green";
+            blue: "blue";
+            purple: "purple";
+        }>>;
+        account_id: z.ZodString;
+        payee_id: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodString>;
+        import_id: z.ZodOptional<z.ZodString>;
+        payee_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CreateTransactionsParams = z.infer<typeof CreateTransactionsSchema>;
+export interface BulkTransactionResult {
+    request_index: number;
+    status: "created" | "duplicate" | "failed";
+    transaction_id?: string | undefined;
+    correlation_key: string;
+    error_code?: string | undefined;
+    error?: string | undefined;
+}
+export interface BulkCreateResponse {
+    success: boolean;
+    server_knowledge?: number;
+    summary: {
+        total_requested: number;
+        created: number;
+        duplicates: number;
+        failed: number;
+    };
+    results: BulkTransactionResult[];
+    transactions?: ynab.TransactionDetail[];
+    duplicate_import_ids?: string[];
+    message?: string;
+    mode?: "full" | "summary" | "ids_only";
+}
+export declare const CreateReceiptSplitTransactionSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    account_id: z.ZodString;
+    payee_name: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+    memo: z.ZodOptional<z.ZodString>;
+    receipt_subtotal: z.ZodOptional<z.ZodNumber>;
+    receipt_tax: z.ZodNumber;
+    receipt_total: z.ZodNumber;
+    categories: z.ZodArray<z.ZodObject<{
+        category_id: z.ZodString;
+        category_name: z.ZodOptional<z.ZodString>;
+        items: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            amount: z.ZodNumber;
+            quantity: z.ZodOptional<z.ZodNumber>;
+            memo: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    cleared: z.ZodOptional<z.ZodEnum<{
+        cleared: "cleared";
+        uncleared: "uncleared";
+        reconciled: "reconciled";
+    }>>;
+    approved: z.ZodOptional<z.ZodBoolean>;
+    flag_color: z.ZodOptional<z.ZodEnum<{
+        red: "red";
+        orange: "orange";
+        yellow: "yellow";
+        green: "green";
+        blue: "blue";
+        purple: "purple";
+    }>>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CreateReceiptSplitTransactionParams = z.infer<typeof CreateReceiptSplitTransactionSchema>;
+export interface ReceiptCategoryCalculation {
+    category_id: string;
+    category_name: string | undefined;
+    subtotal_milliunits: number;
+    tax_milliunits: number;
+    items: {
+        name: string;
+        amount_milliunits: number;
+        quantity: number | undefined;
+        memo: string | undefined;
+    }[];
+}
+export declare const UpdateTransactionSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    transaction_id: z.ZodString;
+    account_id: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    date: z.ZodOptional<z.ZodString>;
+    payee_name: z.ZodOptional<z.ZodString>;
+    payee_id: z.ZodOptional<z.ZodString>;
+    category_id: z.ZodOptional<z.ZodString>;
+    memo: z.ZodOptional<z.ZodString>;
+    cleared: z.ZodOptional<z.ZodEnum<{
+        cleared: "cleared";
+        uncleared: "uncleared";
+        reconciled: "reconciled";
+    }>>;
+    approved: z.ZodOptional<z.ZodBoolean>;
+    flag_color: z.ZodOptional<z.ZodEnum<{
+        red: "red";
+        orange: "orange";
+        yellow: "yellow";
+        green: "green";
+        blue: "blue";
+        purple: "purple";
+    }>>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type UpdateTransactionParams = z.infer<typeof UpdateTransactionSchema>;
+declare const BulkUpdateTransactionInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    amount: z.ZodOptional<z.ZodNumber>;
+    date: z.ZodOptional<z.ZodString>;
+    payee_name: z.ZodOptional<z.ZodString>;
+    payee_id: z.ZodOptional<z.ZodString>;
+    category_id: z.ZodOptional<z.ZodString>;
+    memo: z.ZodOptional<z.ZodString>;
+    cleared: z.ZodOptional<z.ZodEnum<{
+        cleared: "cleared";
+        uncleared: "uncleared";
+        reconciled: "reconciled";
+    }>>;
+    approved: z.ZodOptional<z.ZodBoolean>;
+    flag_color: z.ZodOptional<z.ZodEnum<{
+        red: "red";
+        orange: "orange";
+        yellow: "yellow";
+        green: "green";
+        blue: "blue";
+        purple: "purple";
+    }>>;
+    original_account_id: z.ZodOptional<z.ZodString>;
+    original_date: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type BulkUpdateTransactionInput = z.infer<typeof BulkUpdateTransactionInputSchema>;
+export declare const UpdateTransactionsSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    transactions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        amount: z.ZodOptional<z.ZodNumber>;
+        date: z.ZodOptional<z.ZodString>;
+        payee_name: z.ZodOptional<z.ZodString>;
+        payee_id: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodString>;
+        memo: z.ZodOptional<z.ZodString>;
+        cleared: z.ZodOptional<z.ZodEnum<{
+            cleared: "cleared";
+            uncleared: "uncleared";
+            reconciled: "reconciled";
+        }>>;
+        approved: z.ZodOptional<z.ZodBoolean>;
+        flag_color: z.ZodOptional<z.ZodEnum<{
+            red: "red";
+            orange: "orange";
+            yellow: "yellow";
+            green: "green";
+            blue: "blue";
+            purple: "purple";
+        }>>;
+        original_account_id: z.ZodOptional<z.ZodString>;
+        original_date: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type UpdateTransactionsParams = z.infer<typeof UpdateTransactionsSchema>;
+export interface BulkUpdateResult {
+    request_index: number;
+    status: "updated" | "failed";
+    transaction_id: string;
+    correlation_key: string;
+    error_code?: string;
+    error?: string;
+}
+export interface BulkUpdateResponse {
+    success: boolean;
+    server_knowledge?: number;
+    summary: {
+        total_requested: number;
+        updated: number;
+        failed: number;
+    };
+    results: BulkUpdateResult[];
+    transactions?: ynab.TransactionDetail[];
+    message?: string;
+    mode?: "full" | "summary" | "ids_only";
+}
+export declare const DeleteTransactionSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    transaction_id: z.ZodString;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type DeleteTransactionParams = z.infer<typeof DeleteTransactionSchema>;
+export interface CorrelationPayload {
+    account_id?: string;
+    date?: string;
+    amount?: number;
+    payee_id?: string | null;
+    payee_name?: string | null;
+    category_id?: string | null;
+    memo?: string | null;
+    cleared?: ynab.TransactionClearedStatus;
+    approved?: boolean;
+    flag_color?: ynab.TransactionFlagColor | null;
+    import_id?: string | null;
+}
+export interface CorrelationPayloadInput {
+    account_id?: string | undefined;
+    date?: string | undefined;
+    amount?: number | undefined;
+    payee_id?: string | null | undefined;
+    payee_name?: string | null | undefined;
+    category_id?: string | null | undefined;
+    memo?: string | null | undefined;
+    cleared?: ynab.TransactionClearedStatus | undefined;
+    approved?: boolean | undefined;
+    flag_color?: ynab.TransactionFlagColor | null | undefined;
+    import_id?: string | null | undefined;
+}
+export interface CategorySource {
+    category_id?: string | null;
+    subtransactions?: {
+        category_id?: string | null;
+    }[] | null | undefined;
+}
+export interface TransactionCacheInvalidationOptions {
+    affectedCategoryIds?: Set<string>;
+    invalidateAllCategories?: boolean;
+    accountTotalsChanged?: boolean;
+    invalidateMonths?: boolean;
+}
+export {};