@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/schemas/outputs/comparisonOutputs.ts

@@ -0,0 +1,600 @@
+/**
+ * @fileoverview Transaction comparison and export output schemas for YNAB MCP server.
+ * Defines Zod validation schemas for comparing bank CSV transactions with YNAB transactions
+ * and exporting transactions to JSON files with metadata.
+ *
+ * @see src/tools/compareTransactions/index.ts - Main comparison handler (lines 63-228)
+ * @see src/tools/compareTransactions/types.ts - Type definitions for comparison entities
+ * @see src/tools/compareTransactions/formatter.ts - Result formatting logic
+ * @see src/tools/exportTransactions.ts - Transaction export handler (lines 147-274)
+ *
+ * @example
+ * // Transaction comparison result
+ * {
+ *   summary: {
+ *     total_bank_transactions: 50,
+ *     total_ynab_transactions: 52,
+ *     matched_count: 45,
+ *     unmatched_bank_count: 5,
+ *     unmatched_ynab_count: 7,
+ *     match_rate_percentage: 90.0
+ *   },
+ *   matches: [
+ *     {
+ *       bank_transaction: { date: "2025-10-15", amount: -25500, description: "Grocery Store" },
+ *       ynab_transaction: { id: "txn-1", date: "2025-10-15", amount: -25500, payee_name: "Grocery Store" },
+ *       match_score: 95,
+ *       match_reasons: ["exact_amount_match", "exact_date_match", "payee_similarity"]
+ *     }
+ *   ],
+ *   unmatched_bank: [...],
+ *   parameters: { amount_tolerance: 0, date_tolerance_days: 2 }
+ * }
+ *
+ * @example
+ * // Transaction export result
+ * {
+ *   message: "Successfully exported 150 transactions",
+ *   filename: "ynab_transactions_2025-11-18.json",
+ *   full_path: "/Users/username/Downloads/ynab_transactions_2025-11-18.json",
+ *   export_mode: "full",
+ *   preview_count: 5,
+ *   total_count: 150,
+ *   preview_transactions: [...]
+ * }
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// DATE VALIDATION HELPERS
+// ============================================================================
+
+/**
+ * Validates that a string is both correctly formatted as YYYY-MM-DD and represents
+ * a valid calendar date. Rejects invalid dates like "2024-02-31" or "2024-13-01".
+ *
+ * @param dateStr - ISO date string to validate
+ * @returns true if the date is valid, false otherwise
+ *
+ * @remarks
+ * This validation checks:
+ * 1. Format: YYYY-MM-DD (via regex)
+ * 2. Parseability: Date.parse() succeeds
+ * 3. Calendar validity: Parsed components match original string
+ * 4. Not NaN: The parsed date is a valid number
+ *
+ * @example
+ * isValidISODate("2024-02-29") // true (leap year)
+ * isValidISODate("2024-02-30") // false (February has max 29 days)
+ * isValidISODate("2024-13-01") // false (invalid month)
+ * isValidISODate("2024-02-31") // false (February doesn't have 31 days)
+ */
+function isValidISODate(dateStr: string): boolean {
+  // First check format
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+    return false;
+  }
+
+  // Parse and validate
+  const parsed = Date.parse(dateStr);
+  if (isNaN(parsed)) {
+    return false;
+  }
+
+  // Verify that the parsed date components match the original string
+  // This catches cases like "2024-02-31" which Date.parse might coerce to "2024-03-03"
+  const date = new Date(parsed);
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(date.getUTCDate()).padStart(2, '0');
+  const reconstructed = `${year}-${month}-${day}`;
+
+  return reconstructed === dateStr;
+}
+/**
+ * Reusable Zod schema for validating ISO date strings (YYYY-MM-DD).
+ * Validates both format and calendar validity.
+ *
+ * @example
+ * const schema = z.object({ date: ISODateStringSchema });
+ * schema.parse({ date: "2024-02-29" }); // OK (leap year)
+ * schema.parse({ date: "2024-02-31" }); // Error: Invalid calendar date
+ */
+export const ISODateStringSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
+  .refine(isValidISODate, {
+    message: 'Invalid calendar date (e.g., month must be 01-12, day must be valid for the month)',
+  });
+
+// ============================================================================
+// NESTED SCHEMAS FOR COMPOSITION
+// ============================================================================
+
+/**
+ * Bank transaction for comparison analysis (formatted output).
+ * Represents missing transactions in YNAB with payee suggestions.
+ *
+ * @remarks
+ * The formatter uses `.toFixed(2)` to format amounts as decimal strings with exactly 2 decimal places.
+ * Dates are formatted as ISO strings (YYYY-MM-DD) via `.toISOString().split('T')[0]`.
+ *
+ * @see src/tools/compareTransactions/formatter.ts:92-102 - formatUnmatchedBank function
+ */
+export const MissingInYNABItemSchema = z.object({
+  date: ISODateStringSchema,
+  amount: z
+    .string()
+    .regex(/^-?\d+\.\d{2}$/, 'Amount must be a decimal string with exactly 2 decimal places'),
+  description: z.string(),
+  row_number: z.number(),
+  suggested_payee_id: z.string().optional(),
+  suggested_payee_name: z.string().optional(),
+  suggestion_reason: z.string().optional(),
+});
+
+export type MissingInYNABItem = z.infer<typeof MissingInYNABItemSchema>;
+
+/**
+ * YNAB transaction missing from bank CSV (formatted output).
+ * Represents transactions that exist in YNAB but not in the bank file.
+ *
+ * @remarks
+ * The formatter uses `.toFixed(2)` to format amounts as decimal strings with exactly 2 decimal places.
+ * Dates are formatted as ISO strings (YYYY-MM-DD) via `.toISOString().split('T')[0]`.
+ *
+ * @see src/tools/compareTransactions/formatter.ts:108-116 - formatUnmatchedYNAB function
+ */
+export const MissingInBankItemSchema = z.object({
+  id: z.string(),
+  date: ISODateStringSchema,
+  amount: z
+    .string()
+    .regex(/^-?\d+\.\d{2}$/, 'Amount must be a decimal string with exactly 2 decimal places'),
+  payee_name: z.string().nullable(),
+  memo: z.string().nullable(),
+  cleared: z.string(),
+});
+
+export type MissingInBankItem = z.infer<typeof MissingInBankItemSchema>;
+
+/**
+ * Matched transaction pair (formatted output).
+ * Links a bank transaction to a YNAB transaction with confidence metrics.
+ *
+ * @remarks
+ * The formatter uses `.toFixed(2)` to format amounts as decimal strings with exactly 2 decimal places.
+ * Dates are formatted as ISO strings (YYYY-MM-DD) via `.toISOString().split('T')[0]`.
+ *
+ * @see src/tools/compareTransactions/formatter.ts:72-86 - formatMatches function
+ */
+export const MatchItemSchema = z.object({
+  bank_date: ISODateStringSchema,
+  bank_amount: z
+    .string()
+    .regex(/^-?\d+\.\d{2}$/, 'Amount must be a decimal string with exactly 2 decimal places'),
+  bank_description: z.string(),
+  ynab_date: ISODateStringSchema,
+  ynab_amount: z
+    .string()
+    .regex(/^-?\d+\.\d{2}$/, 'Amount must be a decimal string with exactly 2 decimal places'),
+  ynab_payee: z.string().nullable(),
+  ynab_transaction: z.object({
+    id: z.string(),
+    cleared: z.string(),
+  }),
+  match_score: z.number(),
+  match_reasons: z.array(z.string()),
+});
+
+export type MatchItem = z.infer<typeof MatchItemSchema>;
+
+// ============================================================================
+// INTERNAL SCHEMAS (for reference, not used in main output validation)
+// ============================================================================
+
+/**
+ * Bank transaction (internal type, used during matching).
+ * Not part of the formatted output; see MissingInYNABItemSchema for output format.
+ *
+ * @remarks
+ * **WARNING:** This is an internal schema used during the matching algorithm.
+ * It is NOT part of the public tool output contract and may change without
+ * maintaining backward compatibility. Do not rely on this schema for stable
+ * integrations - use CompareTransactionsOutputSchema instead.
+ *
+ * @see src/tools/compareTransactions/types.ts - BankTransaction interface
+ * @internal
+ */
+export const BankTransactionComparisonSchema = z.object({
+  date: ISODateStringSchema,
+  amount: z.number(),
+  description: z.string(),
+  raw_amount: z.string(),
+  raw_date: z.string(),
+  row_number: z.number(),
+});
+
+export type BankTransactionComparison = z.infer<typeof BankTransactionComparisonSchema>;
+
+/**
+ * YNAB transaction (internal type, used during matching).
+ * Not part of the formatted output; see MissingInBankItemSchema for output format.
+ *
+ * @remarks
+ * **WARNING:** This is an internal schema used during the matching algorithm.
+ * It is NOT part of the public tool output contract and may change without
+ * maintaining backward compatibility. Do not rely on this schema for stable
+ * integrations - use CompareTransactionsOutputSchema instead.
+ *
+ * @see src/tools/compareTransactions/types.ts - YNABTransaction interface
+ * @internal
+ */
+export const YNABTransactionComparisonSchema = z.object({
+  id: z.string(),
+  date: ISODateStringSchema,
+  amount: z.number(),
+  payee_name: z.string().nullable(),
+  memo: z.string().nullable(),
+  cleared: z.string(),
+  account_name: z.string().optional(),
+  category_name: z.string().optional(),
+});
+
+export type YNABTransactionComparison = z.infer<typeof YNABTransactionComparisonSchema>;
+
+/**
+ * Matched transaction pair (internal type, used during matching).
+ * Not part of the formatted output; see MatchItemSchema for output format.
+ *
+ * @remarks
+ * **WARNING:** This is an internal schema used during the matching algorithm.
+ * It is NOT part of the public tool output contract and may change without
+ * maintaining backward compatibility. Do not rely on this schema for stable
+ * integrations - use CompareTransactionsOutputSchema instead.
+ *
+ * @see src/tools/compareTransactions/types.ts - TransactionMatch interface
+ * @internal
+ */
+export const TransactionMatchComparisonSchema = z.object({
+  bank_transaction: BankTransactionComparisonSchema,
+  ynab_transaction: YNABTransactionComparisonSchema,
+  match_score: z.number().min(0).max(100),
+  match_reasons: z.array(z.string()),
+});
+
+export type TransactionMatchComparison = z.infer<typeof TransactionMatchComparisonSchema>;
+
+/**
+ * Comparison configuration parameters.
+ * Documents tolerance settings used for matching.
+ */
+export const ComparisonParametersSchema = z.object({
+  amount_tolerance: z.number().optional(),
+  date_tolerance_days: z.number().optional(),
+});
+
+export type ComparisonParameters = z.infer<typeof ComparisonParametersSchema>;
+
+/**
+ * Date range for comparison analysis.
+ * Specifies the period covered by compared transactions.
+ *
+ * @remarks
+ * Validates that:
+ * 1. Both start and end are valid ISO dates (YYYY-MM-DD)
+ * 2. Start date is before or equal to end date
+ *
+ * @example
+ * DateRangeSchema.parse({ start: "2024-01-01", end: "2024-12-31" }) // OK
+ * DateRangeSchema.parse({ start: "2024-12-31", end: "2024-01-01" }) // Error: start date must be before or equal to end date
+ */
+export const DateRangeSchema = z
+  .object({
+    start: ISODateStringSchema,
+    end: ISODateStringSchema,
+  })
+  .refine(
+    (data) => {
+      // Parse both dates - we know they're valid ISO dates due to ISODateStringSchema
+      const startDate = Date.parse(data.start);
+      const endDate = Date.parse(data.end);
+
+      // Validate logical ordering: start must be <= end
+      return startDate <= endDate;
+    },
+    {
+      message: 'Start date must be before or equal to end date',
+    },
+  );
+
+export type DateRange = z.infer<typeof DateRangeSchema>;
+
+/**
+ * Export metadata and configuration (written to disk).
+ * Documents export settings and timestamp.
+ *
+ * @remarks
+ * This schema represents the export_info object written to the JSON file.
+ * Note: The tool response does NOT include this object - see ExportTransactionsOutputSchema for the tool response format.
+ *
+ * @see src/tools/exportTransactions.ts:184-197 - Export info construction
+ */
+export const ExportInfoSchema = z.object({
+  exported_at: z.string(),
+  total_transactions: z.number(),
+  minimal: z.boolean(),
+  filters: z.object({
+    budget_id: z.string().optional(),
+    account_id: z.string().nullable(),
+    category_id: z.string().nullable(),
+    since_date: z.string().nullable(),
+    type: z.string().nullable(),
+  }),
+});
+
+export type ExportInfo = z.infer<typeof ExportInfoSchema>;
+
+/**
+ * Exported transaction schema (written to disk, no export_mode discriminator).
+ * The actual JSON file does not include an export_mode field on each transaction.
+ *
+ * @remarks
+ * IMPORTANT: `amount` is the raw YNAB amount in **milliunits** (not dollar amounts).
+ * These values come directly from the YNAB API and represent 1/1000th of the currency unit.
+ * For example, $25.50 is represented as 25500 milliunits.
+ *
+ * Minimal mode includes: id, date, amount, payee_name, cleared
+ * Full mode includes: all transaction fields
+ *
+ * @see src/tools/exportTransactions.ts:198-232 - Transaction export logic
+ * @see src/tools/exportTransactions.ts:204 - Amount field directly from transaction.amount (milliunits)
+ */
+export const ExportedTransactionMinimalSchema = z.object({
+  id: z.string(),
+  date: z.string(),
+  amount: z.number(), // Raw YNAB milliunits
+  payee_name: z.string().nullable(),
+  cleared: z.string(),
+});
+
+export const ExportedTransactionFullSchema = z.object({
+  id: z.string(),
+  date: z.string(),
+  amount: z.number(), // Raw YNAB milliunits
+  memo: z.string().nullable(),
+  cleared: z.string(),
+  approved: z.boolean(),
+  flag_color: z.string().nullable(),
+  account_id: z.string(),
+  payee_id: z.string().nullable(),
+  category_id: z.string().nullable(),
+  transfer_account_id: z.string().nullable(),
+  transfer_transaction_id: z.string().nullable(),
+  matched_transaction_id: z.string().nullable(),
+  import_id: z.string().nullable(),
+  deleted: z.boolean(),
+  account_name: z.string().optional(),
+  payee_name: z.string().nullable(),
+  category_name: z.string().nullable(),
+});
+
+export const ExportedTransactionSchema = z.union([
+  ExportedTransactionMinimalSchema,
+  ExportedTransactionFullSchema,
+]);
+
+export type ExportedTransaction = z.infer<typeof ExportedTransactionSchema>;
+
+/**
+ * Complete exported file structure (written to disk).
+ * Represents the full JSON file structure created by export_transactions tool.
+ *
+ * @remarks
+ * This is the structure of the file written to disk, NOT the tool response.
+ * For the tool response format, see ExportTransactionsOutputSchema.
+ *
+ * @see src/tools/exportTransactions.ts:184-233 - Export data construction and file writing
+ *
+ * @example
+ * // Minimal export file
+ * {
+ *   export_info: {
+ *     exported_at: "2025-11-18T10:30:00Z",
+ *     total_transactions: 150,
+ *     minimal: true,
+ *     filters: {
+ *       budget_id: "budget-123",
+ *       account_id: "account-456",
+ *       category_id: null,
+ *       since_date: "2025-01-01",
+ *       type: null,
+ *       minimal: true
+ *     }
+ *   },
+ *   transactions: [
+ *     { id: "txn-1", date: "2025-11-15", amount: -25500, payee_name: "Grocery Store", cleared: "cleared" }, // amount is milliunits
+ *     ...
+ *   ]
+ * }
+ *
+ * @example
+ * // Full export file
+ * {
+ *   export_info: {
+ *     exported_at: "2025-11-18T10:30:00Z",
+ *     total_transactions: 150,
+ *     minimal: false,
+ *     filters: { ... }
+ *   },
+ *   transactions: [
+ *     {
+ *       id: "txn-1",
+ *       date: "2025-11-15",
+ *       amount: -25500, // Raw milliunits: -$25.50
+ *       memo: "Weekly groceries",
+ *       cleared: "cleared",
+ *       approved: true,
+ *       flag_color: null,
+ *       account_id: "account-456",
+ *       payee_id: "payee-789",
+ *       payee_name: "Grocery Store",
+ *       category_id: "category-123",
+ *       category_name: "Food",
+ *       ...
+ *     },
+ *     ...
+ *   ]
+ * }
+ */
+export const ExportFileSchema = z.object({
+  export_info: ExportInfoSchema,
+  transactions: z.array(ExportedTransactionSchema),
+});
+
+export type ExportFile = z.infer<typeof ExportFileSchema>;
+
+// ============================================================================
+// MAIN OUTPUT SCHEMAS
+// ============================================================================
+
+/**
+ * Transaction comparison analysis result.
+ * Returns matched pairs, unmatched transactions, and summary statistics.
+ *
+ * @see src/tools/compareTransactions/formatter.ts - buildComparisonResult function (lines 122-163)
+ * @see src/tools/compareTransactions/formatter.ts - buildSummary function (lines 46-67)
+ *
+ * @example
+ * {
+ *   summary: {
+ *     bank_transactions_count: 50,
+ *     ynab_transactions_count: 52,
+ *     matches_found: 45,
+ *     missing_in_ynab: 5,
+ *     missing_in_bank: 7,
+ *     date_range: { start: "2025-10-01", end: "2025-10-31" },
+ *     parameters: { amount_tolerance: 0, date_tolerance_days: 2 }
+ *   },
+ *   matches: [
+ *     {
+ *       bank_date: "2025-10-15",
+ *       bank_amount: "25.50",
+ *       bank_description: "Grocery Store",
+ *       ynab_date: "2025-10-15",
+ *       ynab_amount: "25.50",
+ *       ynab_payee: "Grocery Store",
+ *       ynab_transaction: { id: "txn-1", cleared: "cleared" },
+ *       match_score: 95,
+ *       match_reasons: ["exact_amount_match", "exact_date_match", "payee_similarity"]
+ *     }
+ *   ],
+ *   missing_in_ynab: [
+ *     {
+ *       date: "2025-10-20",
+ *       amount: "15.00",
+ *       description: "Unknown Store",
+ *       row_number: 12,
+ *       suggested_payee_name: "Unknown Store",
+ *       suggestion_reason: "No matching payee found. Suggested new payee name from description."
+ *     }
+ *   ],
+ *   missing_in_bank: [
+ *     {
+ *       id: "txn-99",
+ *       date: "2025-10-22",
+ *       amount: "20.00",
+ *       payee_name: "Coffee Shop",
+ *       memo: null,
+ *       cleared: "cleared"
+ *     }
+ *   ]
+ * }
+ */
+export const CompareTransactionsOutputSchema = z.object({
+  summary: z.object({
+    bank_transactions_count: z.number(),
+    ynab_transactions_count: z.number(),
+    matches_found: z.number(),
+    missing_in_ynab: z.number(),
+    missing_in_bank: z.number(),
+    date_range: DateRangeSchema,
+    parameters: ComparisonParametersSchema,
+  }),
+  matches: z.array(MatchItemSchema),
+  missing_in_ynab: z.array(MissingInYNABItemSchema),
+  missing_in_bank: z.array(MissingInBankItemSchema),
+});
+
+export type CompareTransactionsOutput = z.infer<typeof CompareTransactionsOutputSchema>;
+
+/**
+ * Transaction export tool response (MCP tool result).
+ * Returns export location, mode, and preview of exported data.
+ *
+ * @remarks
+ * IMPORTANT: This schema represents the tool's response payload, NOT the file contents.
+ * The tool response does NOT include `export_info` or the full `transactions` array.
+ * For the file structure written to disk, see ExportFileSchema.
+ *
+ * @see src/tools/exportTransactions.ts:242-269 - Handler response construction
+ * @see ExportFileSchema - For the JSON file structure written to disk
+ *
+ * @example
+ * // Tool response (minimal export mode)
+ * {
+ *   message: "Successfully exported 150 transactions (minimal fields)",
+ *   filename: "ynab_transactions_minimal_2025-11-18.json",
+ *   full_path: "/Users/username/Downloads/ynab_transactions_minimal_2025-11-18.json",
+ *   export_directory: "/Users/username/Downloads",
+ *   export_mode: "minimal",
+ *   minimal_fields: "id, date, amount, payee_name, cleared",
+ *   filename_explanation: "Filename format: ynab_{filters}_{count}items_{timestamp}.json...",
+ *   preview_count: 10,
+ *   total_count: 150,
+ *   preview_transactions: [
+ *     { id: "txn-1", date: "2025-11-15", amount: -25500, memo: "Groceries", payee_name: "Grocery Store", category_name: "Food" }
+ *   ]
+ * }
+ *
+ * @example
+ * // Tool response (full export mode)
+ * {
+ *   message: "Successfully exported 150 transactions (full fields)",
+ *   filename: "ynab_transactions_2025-11-18.json",
+ *   full_path: "/Users/username/Downloads/ynab_transactions_2025-11-18.json",
+ *   export_directory: "/Users/username/Downloads",
+ *   export_mode: "full",
+ *   minimal_fields: null,
+ *   filename_explanation: "Filename format: ynab_{filters}_{count}items_{timestamp}.json...",
+ *   preview_count: 10,
+ *   total_count: 150,
+ *   preview_transactions: [
+ *     { id: "txn-2", date: "2025-11-16", amount: -15000, memo: "Coffee", payee_name: "Cafe", category_name: "Dining" }
+ *   ]
+ * }
+ */
+export const ExportTransactionsOutputSchema = z.object({
+  message: z.string(),
+  filename: z.string(),
+  full_path: z.string(),
+  export_directory: z.string(),
+  export_mode: z.enum(['minimal', 'full']),
+  minimal_fields: z.string().nullable(),
+  filename_explanation: z.string(),
+  preview_count: z.number(),
+  total_count: z.number(),
+  preview_transactions: z.array(
+    z.object({
+      id: z.string(),
+      date: z.string(),
+      amount: z.number(), // Raw YNAB milliunits
+      memo: z.string().nullable().optional(),
+      payee_name: z.string().nullable().optional(),
+      category_name: z.string().nullable().optional(),
+    }),
+  ),
+});
+
+export type ExportTransactionsOutput = z.infer<typeof ExportTransactionsOutputSchema>;