@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/dist/tools/transactionUtils.d.ts

@@ -0,0 +1,31 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type * as ynab from "ynab";
+import type { SaveTransactionsResponseData } from "ynab/dist/models/SaveTransactionsResponseData.js";
+import type { DeltaCache } from "../server/deltaCache.js";
+import type { ServerKnowledgeStore } from "../server/serverKnowledgeStore.js";
+import type { BulkCreateResponse, BulkTransactionInput, BulkTransactionResult, BulkUpdateResponse, CategorySource, CorrelationPayload, CorrelationPayloadInput, TransactionCacheInvalidationOptions } from "./transactionSchemas.js";
+export declare function ensureTransaction<T>(transaction: T | undefined, errorMessage: string): T;
+export declare function appendCategoryIds(source: CategorySource | undefined, target: Set<string>): void;
+export declare function collectCategoryIdsFromSources(...sources: (CategorySource | undefined)[]): Set<string>;
+export declare function setsEqual<T>(a: Set<T>, b: Set<T>): boolean;
+export declare const toMonthKey: (date: string) => string;
+export declare function invalidateTransactionCaches(deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, budgetId: string, serverKnowledge: number | undefined, affectedAccountIds: Set<string>, affectedMonths: Set<string>, options?: TransactionCacheInvalidationOptions): void;
+export declare function generateCorrelationKey(transaction: {
+    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;
+}): string;
+export declare function toCorrelationPayload(transaction: CorrelationPayloadInput): CorrelationPayload;
+export declare function correlateResults(requests: BulkTransactionInput[], responseData: SaveTransactionsResponseData, duplicateImportIds: Set<string>): BulkTransactionResult[];
+export declare function estimatePayloadSize(payload: BulkCreateResponse | BulkUpdateResponse): number;
+export declare function finalizeResponse(response: BulkCreateResponse): BulkCreateResponse;
+export declare function finalizeBulkUpdateResponse(response: BulkUpdateResponse): BulkUpdateResponse;
+export declare function handleTransactionError(error: unknown, defaultMessage: string): CallToolResult;

package/dist/tools/transactionUtils.js

@@ -0,0 +1,364 @@
+import { createHash } from "node:crypto";
+import { CacheManager, cacheManager } from "../server/cacheManager.js";
+import { globalRequestLogger } from "../server/requestLogger.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import { ValidationError } from "../types/index.js";
+const FULL_RESPONSE_THRESHOLD = 64 * 1024;
+const SUMMARY_RESPONSE_THRESHOLD = 96 * 1024;
+const MAX_RESPONSE_BYTES = 100 * 1024;
+export function ensureTransaction(transaction, errorMessage) {
+    if (!transaction) {
+        throw new Error(errorMessage);
+    }
+    return transaction;
+}
+export function appendCategoryIds(source, target) {
+    if (!source) {
+        return;
+    }
+    if (source.category_id) {
+        target.add(source.category_id);
+    }
+    if (Array.isArray(source.subtransactions)) {
+        for (const sub of source.subtransactions) {
+            if (sub?.category_id) {
+                target.add(sub.category_id);
+            }
+        }
+    }
+}
+export function collectCategoryIdsFromSources(...sources) {
+    const result = new Set();
+    for (const source of sources) {
+        appendCategoryIds(source, result);
+    }
+    return result;
+}
+export function setsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const value of a) {
+        if (!b.has(value)) {
+            return false;
+        }
+    }
+    return true;
+}
+export const toMonthKey = (date) => `${date.slice(0, 7)}-01`;
+export function invalidateTransactionCaches(deltaCache, knowledgeStore, budgetId, serverKnowledge, affectedAccountIds, affectedMonths, options = {}) {
+    deltaCache.invalidate(budgetId, "transactions");
+    cacheManager.delete(CacheManager.generateKey("transactions", "list", budgetId));
+    for (const accountId of affectedAccountIds) {
+        const accountPrefix = CacheManager.generateKey("transactions", "account", budgetId, accountId);
+        cacheManager.deleteByPrefix(accountPrefix);
+    }
+    const invalidateAccountsList = options.accountTotalsChanged ?? true;
+    if (invalidateAccountsList) {
+        cacheManager.delete(CacheManager.generateKey("accounts", "list", budgetId));
+    }
+    for (const accountId of affectedAccountIds) {
+        cacheManager.delete(CacheManager.generateKey("account", "get", budgetId, accountId));
+    }
+    const affectedCategoryIds = options.affectedCategoryIds ?? new Set();
+    const shouldInvalidateCategories = options.invalidateAllCategories || affectedCategoryIds.size > 0;
+    if (shouldInvalidateCategories) {
+        cacheManager.delete(CacheManager.generateKey("categories", "list", budgetId));
+        for (const categoryId of affectedCategoryIds) {
+            cacheManager.delete(CacheManager.generateKey("category", "get", budgetId, categoryId));
+        }
+    }
+    const shouldInvalidateMonths = options.invalidateMonths ?? affectedMonths.size > 0;
+    if (shouldInvalidateMonths) {
+        cacheManager.delete(CacheManager.generateKey("months", "list", budgetId));
+        deltaCache.invalidate(budgetId, "months");
+        for (const month of affectedMonths) {
+            cacheManager.delete(CacheManager.generateKey("month", "get", budgetId, month));
+        }
+    }
+    if (serverKnowledge !== undefined) {
+        const transactionCacheKey = CacheManager.generateKey("transactions", "list", budgetId);
+        knowledgeStore.update(transactionCacheKey, serverKnowledge);
+        if (invalidateAccountsList) {
+            const accountsCacheKey = CacheManager.generateKey("accounts", "list", budgetId);
+            knowledgeStore.update(accountsCacheKey, serverKnowledge);
+        }
+        if (shouldInvalidateMonths && affectedMonths.size > 0) {
+            const monthsCacheKey = CacheManager.generateKey("months", "list", budgetId);
+            knowledgeStore.update(monthsCacheKey, serverKnowledge);
+        }
+    }
+}
+export function generateCorrelationKey(transaction) {
+    if (transaction.import_id) {
+        return transaction.import_id;
+    }
+    const segments = [
+        `account:${transaction.account_id ?? ""}`,
+        `date:${transaction.date ?? ""}`,
+        `amount:${transaction.amount ?? 0}`,
+        `payee:${transaction.payee_id ?? transaction.payee_name ?? ""}`,
+        `category:${transaction.category_id ?? ""}`,
+        `memo:${transaction.memo ?? ""}`,
+        `cleared:${transaction.cleared ?? ""}`,
+        `approved:${transaction.approved ?? false}`,
+        `flag:${transaction.flag_color ?? ""}`,
+    ];
+    const normalized = segments.join("|");
+    const hash = createHash("sha256")
+        .update(normalized)
+        .digest("hex")
+        .slice(0, 16);
+    return `hash:${hash}`;
+}
+export function toCorrelationPayload(transaction) {
+    const payload = {};
+    if (transaction.account_id !== undefined) {
+        payload.account_id = transaction.account_id;
+    }
+    if (transaction.date !== undefined) {
+        payload.date = transaction.date;
+    }
+    if (transaction.amount !== undefined) {
+        payload.amount = transaction.amount;
+    }
+    if (transaction.cleared !== undefined) {
+        payload.cleared = transaction.cleared;
+    }
+    if (transaction.approved !== undefined) {
+        payload.approved = transaction.approved;
+    }
+    if (transaction.flag_color !== undefined) {
+        payload.flag_color = transaction.flag_color;
+    }
+    payload.payee_id = transaction.payee_id ?? null;
+    payload.payee_name = transaction.payee_name ?? null;
+    payload.category_id = transaction.category_id ?? null;
+    payload.memo = transaction.memo ?? null;
+    payload.import_id = transaction.import_id ?? null;
+    return payload;
+}
+export function correlateResults(requests, responseData, duplicateImportIds) {
+    const createdByImportId = new Map();
+    const createdByHash = new Map();
+    const responseTransactions = responseData.transactions ?? [];
+    const register = (map, key, transactionId) => {
+        const existing = map.get(key);
+        if (existing) {
+            existing.push(transactionId);
+            return;
+        }
+        map.set(key, [transactionId]);
+    };
+    for (const transaction of responseTransactions) {
+        if (!transaction.id) {
+            continue;
+        }
+        const key = generateCorrelationKey(transaction);
+        if (key.startsWith("hash:")) {
+            register(createdByHash, key, transaction.id);
+        }
+        else {
+            register(createdByImportId, key, transaction.id);
+        }
+    }
+    const popId = (map, key) => {
+        const bucket = map.get(key);
+        if (!bucket || bucket.length === 0) {
+            return undefined;
+        }
+        const [transactionId] = bucket.splice(0, 1);
+        if (bucket.length === 0) {
+            map.delete(key);
+        }
+        return transactionId;
+    };
+    const correlatedResults = [];
+    for (const [index, transaction] of requests.entries()) {
+        const normalizedRequest = toCorrelationPayload(transaction);
+        const correlationKey = generateCorrelationKey(normalizedRequest);
+        if (transaction.import_id &&
+            duplicateImportIds.has(transaction.import_id)) {
+            correlatedResults.push({
+                request_index: index,
+                status: "duplicate",
+                correlation_key: correlationKey,
+            });
+            continue;
+        }
+        let transactionId;
+        if (correlationKey.startsWith("hash:")) {
+            transactionId = popId(createdByHash, correlationKey);
+        }
+        else {
+            transactionId = popId(createdByImportId, correlationKey);
+        }
+        if (!transactionId && !correlationKey.startsWith("hash:")) {
+            const hashKey = generateCorrelationKey(toCorrelationPayload({ ...transaction, import_id: undefined }));
+            transactionId = popId(createdByHash, hashKey);
+        }
+        if (transactionId) {
+            const successResult = {
+                request_index: index,
+                status: "created",
+                correlation_key: correlationKey,
+            };
+            successResult.transaction_id = transactionId;
+            correlatedResults.push(successResult);
+            continue;
+        }
+        globalRequestLogger.logError("ynab:create_transactions", "correlate_results", {
+            request_index: index,
+            correlation_key: correlationKey,
+            request: {
+                account_id: transaction.account_id,
+                date: transaction.date,
+                amount: transaction.amount,
+                import_id: transaction.import_id,
+            },
+        }, "correlation_failed");
+        correlatedResults.push({
+            request_index: index,
+            status: "failed",
+            correlation_key: correlationKey,
+            error_code: "correlation_failed",
+            error: "Unable to correlate request transaction with YNAB response",
+        });
+    }
+    return correlatedResults;
+}
+export function estimatePayloadSize(payload) {
+    return Buffer.byteLength(JSON.stringify(payload), "utf8");
+}
+export function finalizeResponse(response) {
+    const appendMessage = (message, addition) => {
+        if (!message) {
+            return addition;
+        }
+        if (message.includes(addition)) {
+            return message;
+        }
+        return `${message} ${addition}`;
+    };
+    const fullSize = estimatePayloadSize({ ...response, mode: "full" });
+    if (fullSize <= FULL_RESPONSE_THRESHOLD) {
+        return { ...response, mode: "full" };
+    }
+    const { transactions, ...summaryResponse } = response;
+    const summaryPayload = {
+        ...summaryResponse,
+        message: appendMessage(response.message, "Response downgraded to summary to stay under size limits."),
+        mode: "summary",
+    };
+    if (estimatePayloadSize(summaryPayload) <= SUMMARY_RESPONSE_THRESHOLD) {
+        return summaryPayload;
+    }
+    const idsOnlyPayload = {
+        ...summaryPayload,
+        results: summaryResponse.results.map((result) => ({
+            request_index: result.request_index,
+            status: result.status,
+            transaction_id: result.transaction_id,
+            correlation_key: result.correlation_key,
+            error: result.error,
+        })),
+        message: appendMessage(summaryResponse.message, "Response downgraded to ids_only to meet 100KB limit."),
+        mode: "ids_only",
+    };
+    if (estimatePayloadSize(idsOnlyPayload) <= MAX_RESPONSE_BYTES) {
+        return idsOnlyPayload;
+    }
+    throw new ValidationError("RESPONSE_TOO_LARGE: Unable to format bulk create response within 100KB limit", `Batch size: ${response.summary.total_requested} transactions`, [
+        "Reduce the batch size and retry",
+        "Consider splitting into multiple smaller batches",
+    ]);
+}
+export function finalizeBulkUpdateResponse(response) {
+    const appendMessage = (message, addition) => {
+        if (!message) {
+            return addition;
+        }
+        if (message.includes(addition)) {
+            return message;
+        }
+        return `${message} ${addition}`;
+    };
+    const fullSize = estimatePayloadSize(response);
+    if (fullSize <= FULL_RESPONSE_THRESHOLD) {
+        return { ...response, mode: "full" };
+    }
+    const { transactions, ...summaryResponse } = response;
+    const summaryPayload = {
+        ...summaryResponse,
+        message: appendMessage(response.message, "Response downgraded to summary to stay under size limits."),
+        mode: "summary",
+    };
+    if (estimatePayloadSize(summaryPayload) <= SUMMARY_RESPONSE_THRESHOLD) {
+        return summaryPayload;
+    }
+    const idsOnlyPayload = {
+        ...summaryPayload,
+        results: summaryResponse.results.map((result) => {
+            const simplified = {
+                request_index: result.request_index,
+                status: result.status,
+                transaction_id: result.transaction_id,
+                correlation_key: result.correlation_key,
+            };
+            if (result.error) {
+                simplified.error = result.error;
+            }
+            if (result.error_code) {
+                simplified.error_code = result.error_code;
+            }
+            return simplified;
+        }),
+        message: appendMessage(summaryResponse.message, "Response downgraded to ids_only to meet 100KB limit."),
+        mode: "ids_only",
+    };
+    if (estimatePayloadSize(idsOnlyPayload) <= MAX_RESPONSE_BYTES) {
+        return idsOnlyPayload;
+    }
+    throw new ValidationError("RESPONSE_TOO_LARGE: Unable to format bulk update response within 100KB limit", `Batch size: ${response.summary.total_requested} transactions`, [
+        "Reduce the batch size and retry",
+        "Consider splitting into multiple smaller batches",
+    ]);
+}
+export function handleTransactionError(error, defaultMessage) {
+    let errorMessage = defaultMessage;
+    if (error instanceof Error) {
+        if (error.message.includes("401") ||
+            error.message.includes("Unauthorized")) {
+            errorMessage = "Invalid or expired YNAB access token";
+        }
+        else if (error.message.includes("403") ||
+            error.message.includes("Forbidden")) {
+            errorMessage = "Insufficient permissions to access YNAB data";
+        }
+        else if (error.message.includes("404") ||
+            error.message.includes("Not Found")) {
+            errorMessage = "Budget, account, category, or transaction not found";
+        }
+        else if (error.message.includes("429") ||
+            error.message.includes("Too Many Requests")) {
+            errorMessage = "Rate limit exceeded. Please try again later";
+        }
+        else if (error.message.includes("500") ||
+            error.message.includes("Internal Server Error")) {
+            errorMessage = "YNAB service is currently unavailable";
+        }
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: responseFormatter.format({
+                    error: {
+                        message: errorMessage,
+                    },
+                }),
+            },
+        ],
+    };
+}

package/dist/tools/transactionWriteTools.d.ts

@@ -0,0 +1,20 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type * as ynab from "ynab";
+import type { DeltaCache } from "../server/deltaCache.js";
+import type { ServerKnowledgeStore } from "../server/serverKnowledgeStore.js";
+import type { ToolRegistry } from "../server/toolRegistry.js";
+import type { ToolContext } from "../types/toolRegistration.js";
+import { type CreateReceiptSplitTransactionParams, type CreateTransactionParams, type CreateTransactionsParams, type DeleteTransactionParams, type UpdateTransactionParams, type UpdateTransactionsParams } from "./transactionSchemas.js";
+export declare function handleCreateTransaction(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: CreateTransactionParams): Promise<CallToolResult>;
+export declare function handleCreateTransaction(ynabAPI: ynab.API, params: CreateTransactionParams): Promise<CallToolResult>;
+export declare function handleCreateReceiptSplitTransaction(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: CreateReceiptSplitTransactionParams): Promise<CallToolResult>;
+export declare function handleCreateReceiptSplitTransaction(ynabAPI: ynab.API, params: CreateReceiptSplitTransactionParams): Promise<CallToolResult>;
+export declare function handleUpdateTransaction(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: UpdateTransactionParams): Promise<CallToolResult>;
+export declare function handleUpdateTransaction(ynabAPI: ynab.API, params: UpdateTransactionParams): Promise<CallToolResult>;
+export declare function handleDeleteTransaction(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: DeleteTransactionParams): Promise<CallToolResult>;
+export declare function handleDeleteTransaction(ynabAPI: ynab.API, params: DeleteTransactionParams): Promise<CallToolResult>;
+export declare function handleCreateTransactions(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: CreateTransactionsParams): Promise<CallToolResult>;
+export declare function handleCreateTransactions(ynabAPI: ynab.API, params: CreateTransactionsParams): Promise<CallToolResult>;
+export declare function handleUpdateTransactions(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: UpdateTransactionsParams): Promise<CallToolResult>;
+export declare function handleUpdateTransactions(ynabAPI: ynab.API, params: UpdateTransactionsParams): Promise<CallToolResult>;
+export declare function registerTransactionWriteTools(registry: ToolRegistry, context: ToolContext): void;