@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/tools/transactionSchemas.ts

@@ -0,0 +1,484 @@
+import type * as ynab from "ynab";
+import { z } from "zod/v4";
+
+/**
+ * Transaction Schemas and Types
+ *
+ * This module contains all Zod schemas and TypeScript types for transaction-related tools.
+ * Extracted from transactionTools.ts for better code organization.
+ */
+
+// ============================================================================
+// List Transactions
+// ============================================================================
+
+/**
+ * Schema for ynab:list_transactions tool parameters
+ */
+export const ListTransactionsSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		account_id: z.string().optional(),
+		category_id: z.string().optional(),
+		since_date: z
+			.string()
+			.regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in ISO format (YYYY-MM-DD)")
+			.optional(),
+		type: z.enum(["uncategorized", "unapproved"]).optional(),
+	})
+	.strict();
+
+export type ListTransactionsParams = z.infer<typeof ListTransactionsSchema>;
+
+// ============================================================================
+// Get Transaction
+// ============================================================================
+
+/**
+ * Schema for ynab:get_transaction tool parameters
+ */
+export const GetTransactionSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		transaction_id: z.string().min(1, "Transaction ID is required"),
+	})
+	.strict();
+
+export type GetTransactionParams = z.infer<typeof GetTransactionSchema>;
+
+// ============================================================================
+// Create Transaction
+// ============================================================================
+
+/**
+ * Schema for ynab:create_transaction tool parameters
+ */
+export const CreateTransactionSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		account_id: z.string().min(1, "Account ID is required"),
+		amount: z.number().int("Amount must be an integer in milliunits"),
+		date: z
+			.string()
+			.regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in ISO format (YYYY-MM-DD)"),
+		payee_name: z.string().optional(),
+		payee_id: z.string().optional(),
+		category_id: z.string().optional(),
+		memo: z.string().optional(),
+		cleared: z.enum(["cleared", "uncleared", "reconciled"]).optional(),
+		approved: z.boolean().optional(),
+		flag_color: z
+			.enum(["red", "orange", "yellow", "green", "blue", "purple"])
+			.optional(),
+		import_id: z.string().min(1, "Import ID cannot be empty").optional(),
+		dry_run: z.boolean().optional(),
+		subtransactions: z
+			.array(
+				z
+					.object({
+						amount: z
+							.number()
+							.int("Subtransaction amount must be an integer in milliunits"),
+						payee_name: z.string().optional(),
+						payee_id: z.string().optional(),
+						category_id: z.string().optional(),
+						memo: z.string().optional(),
+					})
+					.strict(),
+			)
+			.min(1, "At least one subtransaction is required when provided")
+			.optional(),
+	})
+	.strict()
+	.superRefine((data, ctx) => {
+		if (data.subtransactions && data.subtransactions.length > 0) {
+			const total = data.subtransactions.reduce(
+				(sum, sub) => sum + sub.amount,
+				0,
+			);
+			if (total !== data.amount) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: "Amount must equal the sum of subtransaction amounts",
+					path: ["amount"],
+				});
+			}
+		}
+	});
+
+export type CreateTransactionParams = z.infer<typeof CreateTransactionSchema>;
+
+/**
+ * Schema for subtransaction input
+ */
+export interface SubtransactionInput {
+	amount: number;
+	payee_name?: string;
+	payee_id?: string;
+	category_id?: string;
+	memo?: string;
+}
+
+// ============================================================================
+// Create Transactions (Bulk)
+// ============================================================================
+
+const BulkTransactionInputSchemaBase = CreateTransactionSchema.pick({
+	account_id: true,
+	amount: true,
+	date: true,
+	payee_name: true,
+	payee_id: true,
+	category_id: true,
+	memo: true,
+	cleared: true,
+	approved: true,
+	flag_color: true,
+	import_id: true,
+});
+
+export type BulkTransactionInput = Omit<
+	CreateTransactionParams,
+	"budget_id" | "dry_run" | "subtransactions"
+>;
+
+// Schema for bulk transaction creation - subtransactions are not supported
+// The .strict() modifier automatically rejects any fields not in the schema
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
+
+export const CreateTransactionsSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		transactions: z
+			.array(BulkTransactionInputSchema)
+			.min(1, "At least one transaction is required")
+			.max(100, "A maximum of 100 transactions may be created at once"),
+		dry_run: z.boolean().optional(),
+	})
+	.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";
+}
+
+// ============================================================================
+// Create Receipt Split Transaction
+// ============================================================================
+
+const ReceiptSplitItemSchema = z
+	.object({
+		name: z.string().min(1, "Item name is required"),
+		amount: z.number().finite("Item amount must be a finite number"),
+		quantity: z
+			.number()
+			.finite("Quantity must be a finite number")
+			.positive("Quantity must be greater than zero")
+			.optional(),
+		memo: z.string().optional(),
+	})
+	.strict();
+
+const ReceiptSplitCategorySchema = z
+	.object({
+		category_id: z.string().min(1, "Category ID is required"),
+		category_name: z.string().optional(),
+		items: z
+			.array(ReceiptSplitItemSchema)
+			.min(1, "Each category must include at least one item"),
+	})
+	.strict();
+
+export const CreateReceiptSplitTransactionSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		account_id: z.string().min(1, "Account ID is required"),
+		payee_name: z.string().min(1, "Payee name is required"),
+		date: z
+			.string()
+			.regex(
+				/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/,
+				"Date must be in ISO format (YYYY-MM-DD)",
+			)
+			.optional(),
+		memo: z.string().optional(),
+		receipt_subtotal: z
+			.number()
+			.finite("Receipt subtotal must be a finite number")
+			.refine((value) => value >= 0, "Receipt subtotal must be zero or greater")
+			.optional(),
+		receipt_tax: z.number().finite("Receipt tax must be a finite number"),
+		receipt_total: z
+			.number()
+			.finite("Receipt total must be a finite number")
+			.refine((value) => value > 0, "Receipt total must be greater than zero"),
+		categories: z
+			.array(ReceiptSplitCategorySchema)
+			.min(
+				1,
+				"At least one categorized group is required to create a split transaction",
+			),
+		cleared: z.enum(["cleared", "uncleared", "reconciled"]).optional(),
+		approved: z.boolean().optional(),
+		flag_color: z
+			.enum(["red", "orange", "yellow", "green", "blue", "purple"])
+			.optional(),
+		dry_run: z.boolean().optional(),
+	})
+	.strict()
+	.superRefine((data, ctx) => {
+		const itemsSubtotal = data.categories
+			.flatMap((category) => category.items)
+			.reduce((sum, item) => sum + item.amount, 0);
+
+		if (data.receipt_subtotal !== undefined) {
+			const delta = Math.abs(data.receipt_subtotal - itemsSubtotal);
+			if (delta > 0.01) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: `Receipt subtotal (${data.receipt_subtotal.toFixed(2)}) does not match categorized items total (${itemsSubtotal.toFixed(2)})`,
+					path: ["receipt_subtotal"],
+				});
+			}
+		}
+
+		const expectedTotal = itemsSubtotal + data.receipt_tax;
+		const deltaTotal = Math.abs(expectedTotal - data.receipt_total);
+		if (deltaTotal > 0.01) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `Receipt total (${data.receipt_total.toFixed(2)}) does not match subtotal plus tax (${expectedTotal.toFixed(2)})`,
+				path: ["receipt_total"],
+			});
+		}
+	});
+
+export type CreateReceiptSplitTransactionParams = z.infer<
+	typeof CreateReceiptSplitTransactionSchema
+>;
+
+/**
+ * Interface for receipt category calculation
+ */
+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;
+	}[];
+}
+
+// ============================================================================
+// Update Transaction
+// ============================================================================
+
+/**
+ * Schema for ynab:update_transaction tool parameters
+ */
+export const UpdateTransactionSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		transaction_id: z.string().min(1, "Transaction ID is required"),
+		account_id: z.string().optional(),
+		amount: z
+			.number()
+			.int("Amount must be an integer in milliunits")
+			.optional(),
+		date: z
+			.string()
+			.regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in ISO format (YYYY-MM-DD)")
+			.optional(),
+		payee_name: z.string().optional(),
+		payee_id: z.string().optional(),
+		category_id: z.string().optional(),
+		memo: z.string().optional(),
+		cleared: z.enum(["cleared", "uncleared", "reconciled"]).optional(),
+		approved: z.boolean().optional(),
+		flag_color: z
+			.enum(["red", "orange", "yellow", "green", "blue", "purple"])
+			.optional(),
+		dry_run: z.boolean().optional(),
+	})
+	.strict();
+
+export type UpdateTransactionParams = z.infer<typeof UpdateTransactionSchema>;
+
+// ============================================================================
+// Update Transactions (Bulk)
+// ============================================================================
+
+/**
+ * Schema for bulk transaction updates - each item in the array
+ * Note: account_id is intentionally excluded as account moves are not supported in bulk updates
+ */
+const BulkUpdateTransactionInputSchema = z
+	.object({
+		id: z.string().min(1, "Transaction ID is required"),
+		amount: z
+			.number()
+			.int("Amount must be an integer in milliunits")
+			.optional(),
+		date: z
+			.string()
+			.regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in ISO format (YYYY-MM-DD)")
+			.optional(),
+		payee_name: z.string().optional(),
+		payee_id: z.string().optional(),
+		category_id: z.string().optional(),
+		memo: z.string().optional(),
+		cleared: z.enum(["cleared", "uncleared", "reconciled"]).optional(),
+		approved: z.boolean().optional(),
+		flag_color: z
+			.enum(["red", "orange", "yellow", "green", "blue", "purple"])
+			.optional(),
+		// Metadata fields for cache invalidation
+		original_account_id: z.string().optional(),
+		original_date: z
+			.string()
+			.regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in ISO format (YYYY-MM-DD)")
+			.optional(),
+	})
+	.strict();
+
+export type BulkUpdateTransactionInput = z.infer<
+	typeof BulkUpdateTransactionInputSchema
+>;
+
+/**
+ * Schema for ynab:update_transactions tool parameters
+ */
+export const UpdateTransactionsSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		transactions: z
+			.array(BulkUpdateTransactionInputSchema)
+			.min(1, "At least one transaction is required")
+			.max(100, "A maximum of 100 transactions may be updated at once"),
+		dry_run: z.boolean().optional(),
+	})
+	.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";
+}
+
+// ============================================================================
+// Delete Transaction
+// ============================================================================
+
+/**
+ * Schema for ynab:delete_transaction tool parameters
+ */
+export const DeleteTransactionSchema = z
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		transaction_id: z.string().min(1, "Transaction ID is required"),
+		dry_run: z.boolean().optional(),
+	})
+	.strict();
+
+export type DeleteTransactionParams = z.infer<typeof DeleteTransactionSchema>;
+
+// ============================================================================
+// Correlation & Utility Types
+// ============================================================================
+
+/**
+ * Type for correlation payload used in bulk operations
+ */
+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;
+}
+
+/**
+ * Interface for correlation payload input (with optional fields)
+ */
+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;
+}
+
+/**
+ * Interface for category source (used in cache invalidation)
+ */
+export interface CategorySource {
+	category_id?: string | null;
+	subtransactions?: { category_id?: string | null }[] | null | undefined;
+}
+
+/**
+ * Interface for transaction cache invalidation options
+ */
+export interface TransactionCacheInvalidationOptions {
+	affectedCategoryIds?: Set<string>;
+	invalidateAllCategories?: boolean;
+	accountTotalsChanged?: boolean;
+	invalidateMonths?: boolean;
+}