@dizzlkheinz/ynab-mcpb 0.12.1

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

@@ -0,0 +1,270 @@
+/**
+ * @fileoverview Central export point for all output schemas
+ *
+ * This file provides a single import location for all output validation schemas
+ * used throughout the YNAB MCP server. Import from this file rather than
+ * individual schema files for convenience and consistency.
+ *
+ * Includes schemas for: utilities, budgets, accounts, transactions (list/get),
+ * categories, payees, months, transaction mutations (create/update/delete),
+ * reconciliation analysis, and comparison/export operations.
+ *
+ * @example
+ * ```typescript
+ * import { GetUserOutputSchema, type GetUserOutput } from './schemas/outputs/index.js';
+ * import { ListBudgetsOutputSchema, type ListBudgetsOutput } from './schemas/outputs/index.js';
+ * import { CreateTransactionOutputSchema, type CreateTransactionOutput } from './schemas/outputs/index.js';
+ * ```
+ */
+
+// ============================================================================
+// UTILITY TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+// Main output schemas
+export {
+  GetUserOutputSchema,
+  type GetUserOutput,
+  ConvertAmountOutputSchema,
+  type ConvertAmountOutput,
+  GetDefaultBudgetOutputSchema,
+  type GetDefaultBudgetOutput,
+  SetDefaultBudgetOutputSchema,
+  type SetDefaultBudgetOutput,
+  ClearCacheOutputSchema,
+  type ClearCacheOutput,
+  SetOutputFormatOutputSchema,
+  type SetOutputFormatOutput,
+  DiagnosticInfoOutputSchema,
+  type DiagnosticInfoOutput,
+  GetBudgetOutputSchema,
+  type GetBudgetOutput,
+} from './utilityOutputs.js';
+
+// Nested schemas that may be useful independently
+export {
+  UserSchema,
+  ConversionSchema,
+  DateFormatSchema,
+  CurrencyFormatSchema,
+  BudgetDetailSchema,
+  ServerInfoSchema,
+  MemoryInfoSchema,
+  EnvironmentInfoSchema,
+  CacheInfoSchema,
+  DeltaInfoSchema,
+} from './utilityOutputs.js';
+
+// ============================================================================
+// BUDGET TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  ListBudgetsOutputSchema,
+  type ListBudgetsOutput,
+  BudgetSummarySchema,
+  type BudgetSummary,
+} from './budgetOutputs.js';
+
+// ============================================================================
+// ACCOUNT TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  ListAccountsOutputSchema,
+  type ListAccountsOutput,
+  GetAccountOutputSchema,
+  type GetAccountOutput,
+  AccountSchema,
+  type Account,
+} from './accountOutputs.js';
+
+// ============================================================================
+// TRANSACTION TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  ListTransactionsOutputSchema,
+  type ListTransactionsOutput,
+  GetTransactionOutputSchema,
+  type GetTransactionOutput,
+  TransactionSchema,
+  type Transaction,
+  TransactionPreviewSchema,
+  type TransactionPreview,
+} from './transactionOutputs.js';
+
+// ============================================================================
+// CATEGORY TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  ListCategoriesOutputSchema,
+  type ListCategoriesOutput,
+  GetCategoryOutputSchema,
+  type GetCategoryOutput,
+  CategorySchema,
+  type Category,
+  CategoryGroupSchema,
+  type CategoryGroup,
+} from './categoryOutputs.js';
+
+// ============================================================================
+// PAYEE TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  ListPayeesOutputSchema,
+  type ListPayeesOutput,
+  GetPayeeOutputSchema,
+  type GetPayeeOutput,
+  PayeeSchema,
+  type Payee,
+} from './payeeOutputs.js';
+
+// ============================================================================
+// MONTH TOOL OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  GetMonthOutputSchema,
+  type GetMonthOutput,
+  ListMonthsOutputSchema,
+  type ListMonthsOutput,
+  MonthDetailSchema,
+  type MonthDetail,
+  MonthSummarySchema,
+  type MonthSummary,
+  MonthCategorySchema,
+  type MonthCategory,
+} from './monthOutputs.js';
+
+// ============================================================================
+// TRANSACTION MUTATION OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  CreateTransactionOutputSchema,
+  type CreateTransactionOutput,
+  CreateTransactionsOutputSchema,
+  type CreateTransactionsOutput,
+  UpdateTransactionOutputSchema,
+  type UpdateTransactionOutput,
+  UpdateTransactionsOutputSchema,
+  type UpdateTransactionsOutput,
+  DeleteTransactionOutputSchema,
+  type DeleteTransactionOutput,
+  CreateReceiptSplitTransactionOutputSchema,
+  type CreateReceiptSplitTransactionOutput,
+  CreateAccountOutputSchema,
+  type CreateAccountOutput,
+  UpdateCategoryOutputSchema,
+  type UpdateCategoryOutput,
+} from './transactionMutationOutputs.js';
+
+// Nested schemas for transaction mutations
+export {
+  SubtransactionSchema,
+  type Subtransaction,
+  SubtransactionPreviewSchema,
+  type SubtransactionPreview,
+  TransactionWithBalanceSchema,
+  type TransactionWithBalance,
+  TransactionDryRunPreviewSchema,
+  type TransactionDryRunPreview,
+  ReceiptItemSchema,
+  type ReceiptItem,
+  ReceiptCategoryBreakdownSchema,
+  type ReceiptCategoryBreakdown,
+  ReceiptSummarySchema,
+  type ReceiptSummary,
+  BulkOperationSummarySchema,
+  type BulkOperationSummary,
+  BulkResultSchema,
+  type BulkResult,
+  DryRunPreviewItemSchema,
+  type DryRunPreviewItem,
+  DryRunWarningSchema,
+  type DryRunWarning,
+} from './transactionMutationOutputs.js';
+
+// ============================================================================
+// RECONCILIATION OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  ReconcileAccountOutputSchema,
+  type ReconcileAccountOutput,
+} from './reconciliationOutputs.js';
+
+// Nested schemas for reconciliation
+export {
+  MoneyValueSchema,
+  type MoneyValue,
+  BankTransactionSchema,
+  type BankTransaction,
+  YNABTransactionSimpleSchema,
+  type YNABTransactionSimple,
+  MatchCandidateSchema,
+  type MatchCandidate,
+  TransactionMatchSchema,
+  type TransactionMatch,
+  BalanceInfoSchema,
+  type BalanceInfo,
+  ReconciliationSummarySchema,
+  type ReconciliationSummary,
+  ReconciliationInsightSchema,
+  type ReconciliationInsight,
+  ActionableRecommendationSchema,
+  type ActionableRecommendation,
+  ExecutionResultSchema,
+  type ExecutionResult,
+  AuditMetadataSchema,
+  type AuditMetadata,
+} from './reconciliationOutputs.js';
+
+// ============================================================================
+// COMPARISON AND EXPORT OUTPUT SCHEMAS
+// ============================================================================
+
+export {
+  CompareTransactionsOutputSchema,
+  type CompareTransactionsOutput,
+  ExportTransactionsOutputSchema,
+  type ExportTransactionsOutput,
+} from './comparisonOutputs.js';
+
+/**
+ * Nested schemas for comparison and export.
+ *
+ * @remarks
+ * Some of these schemas are for internal processing and not guaranteed to be stable:
+ * - **Internal-only (may change):** BankTransactionComparisonSchema, YNABTransactionComparisonSchema,
+ *   TransactionMatchComparisonSchema - Used during matching algorithm, not in final output
+ * - **Public contracts (stable):** ComparisonParametersSchema, DateRangeSchema, ExportInfoSchema,
+ *   ExportedTransactionSchema - Part of durable tool output format
+ *
+ * Internal schemas are exported for testing and advanced use cases, but should not be relied upon
+ * for backward compatibility. Use the main output schemas (CompareTransactionsOutputSchema,
+ * ExportTransactionsOutputSchema) for stable contracts.
+ */
+export {
+  /** @internal - Used during matching algorithm, not part of public output */
+  BankTransactionComparisonSchema,
+  type BankTransactionComparison,
+  /** @internal - Used during matching algorithm, not part of public output */
+  YNABTransactionComparisonSchema,
+  type YNABTransactionComparison,
+  /** @internal - Used during matching algorithm, not part of public output */
+  TransactionMatchComparisonSchema,
+  type TransactionMatchComparison,
+  // Public contracts below - part of stable tool output
+  ComparisonParametersSchema,
+  type ComparisonParameters,
+  DateRangeSchema,
+  type DateRange,
+  ExportInfoSchema,
+  type ExportInfo,
+  ExportedTransactionSchema,
+  type ExportedTransaction,
+} from './comparisonOutputs.js';

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

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview Output schemas for month-related tools.
+ *
+ * Defines Zod schemas and TypeScript types for responses from month tools:
+ * - `get_month`: Returns detailed month data including categories with cache metadata
+ * - `list_months`: Returns summary of all months without category details
+ *
+ * Note: The schemas distinguish between detailed month data (with categories array)
+ * and summary data (without categories array).
+ *
+ * @see src/tools/monthTools.ts:38-104 for get_month handler
+ * @see src/tools/monthTools.ts:110-164 for list_months handler
+ *
+ * @example
+ * ```typescript
+ * const getOutput: GetMonthOutput = {
+ *   month: {
+ *     month: '2025-11-01',
+ *     note: 'November budget',
+ *     income: 5000.00,
+ *     budgeted: 4500.00,
+ *     activity: -4200.00,
+ *     to_be_budgeted: 300.00,
+ *     age_of_money: 45,
+ *     deleted: false,
+ *     categories: [
+ *       {
+ *         id: 'category-123',
+ *         category_group_id: 'group-456',
+ *         category_group_name: 'Monthly Bills',
+ *         name: 'Electricity',
+ *         hidden: false,
+ *         budgeted: 150.00,
+ *         activity: -145.50,
+ *         balance: 204.50,
+ *         goal_type: 'TB',
+ *         goal_target: 150000,
+ *         deleted: false
+ *       }
+ *     ]
+ *   },
+ *   cached: true,
+ *   cache_info: {
+ *     cache_key: 'month:budget-123:2025-11-01',
+ *     age_ms: 2000,
+ *     stale: false
+ *   }
+ * };
+ *
+ * const listOutput: ListMonthsOutput = {
+ *   months: [
+ *     {
+ *       month: '2025-11-01',
+ *       note: 'November budget',
+ *       income: 5000.00,
+ *       budgeted: 4500.00,
+ *       activity: -4200.00,
+ *       to_be_budgeted: 300.00,
+ *       age_of_money: 45,
+ *       deleted: false
+ *     },
+ *     {
+ *       month: '2025-10-01',
+ *       income: 5000.00,
+ *       budgeted: 4800.00,
+ *       activity: -4750.00,
+ *       to_be_budgeted: 50.00,
+ *       age_of_money: 42,
+ *       deleted: false
+ *     }
+ *   ],
+ *   cached: true,
+ *   cache_info: {
+ *     cache_key: 'months:budget-123',
+ *     age_ms: 5000,
+ *     stale: false
+ *   }
+ * };
+ * ```
+ */
+
+import { z } from 'zod/v4';
+import { CacheMetadataSchema } from '../shared/commonOutputs.js';
+
+/**
+ * Schema for a category within month data.
+ *
+ * Similar to CategorySchema but includes additional goal-related fields
+ * specific to month budget data.
+ */
+export const MonthCategorySchema = z.object({
+  /** Unique identifier for the category */
+  id: z.string().describe('Category ID'),
+
+  /** Category group ID this category belongs to */
+  category_group_id: z.string().describe('Category group ID'),
+
+  /** Category group name (optional) */
+  category_group_name: z.string().optional().describe('Category group name'),
+
+  /** Human-readable category name */
+  name: z.string().describe('Category name'),
+
+  /** Whether category is hidden */
+  hidden: z.boolean().describe('Hidden flag'),
+
+  /** Original category group ID if moved (optional) */
+  original_category_group_id: z.string().optional().describe('Original category group ID'),
+
+  /** Optional category note */
+  note: z.string().optional().describe('Category note'),
+
+  /** Budgeted amount in dollars */
+  budgeted: z.number().describe('Budgeted amount in dollars'),
+
+  /** Activity (spending) in dollars */
+  activity: z.number().describe('Activity in dollars'),
+
+  /** Current balance in dollars */
+  balance: z.number().describe('Balance in dollars'),
+
+  /** Goal type (TB, TBD, MF, NEED, DEBT, optional) */
+  goal_type: z.string().optional().describe('Goal type'),
+
+  /** Goal creation month (YYYY-MM-DD, optional) */
+  goal_creation_month: z.string().optional().describe('Goal creation month'),
+
+  /** Goal target amount in milliunits (optional) */
+  goal_target: z.number().optional().describe('Goal target in milliunits'),
+
+  /** Goal target month (YYYY-MM-DD, optional) */
+  goal_target_month: z.string().optional().describe('Goal target month'),
+
+  /** Goal percentage complete (optional) */
+  goal_percentage_complete: z.number().optional().describe('Goal percentage complete'),
+
+  /** Goal months to budget (optional) */
+  goal_months_to_budget: z.number().optional().describe('Goal months to budget'),
+
+  /** Goal under funded amount (optional) */
+  goal_under_funded: z.number().optional().describe('Goal under funded amount'),
+
+  /** Goal overall funded amount (optional) */
+  goal_overall_funded: z.number().optional().describe('Goal overall funded amount'),
+
+  /** Goal overall left amount (optional) */
+  goal_overall_left: z.number().optional().describe('Goal overall left amount'),
+
+  /** Whether category is deleted */
+  deleted: z.boolean().describe('Deleted flag'),
+});
+
+/**
+ * Schema for detailed month data (includes categories array).
+ *
+ * Used by get_month to return complete month details.
+ */
+export const MonthDetailSchema = z.object({
+  /** Month identifier (YYYY-MM-DD format, first day of month) */
+  month: z.string().describe('Month identifier'),
+
+  /** Optional month note */
+  note: z.string().optional().describe('Month note'),
+
+  /** Total income for the month in dollars */
+  income: z.number().describe('Income in dollars'),
+
+  /** Total budgeted for the month in dollars */
+  budgeted: z.number().describe('Budgeted amount in dollars'),
+
+  /** Total activity (spending) for the month in dollars */
+  activity: z.number().describe('Activity in dollars'),
+
+  /** Amount to be budgeted in dollars */
+  to_be_budgeted: z.number().describe('To be budgeted in dollars'),
+
+  /** Age of money in days (optional, can be null if insufficient history) */
+  age_of_money: z.number().nullish().describe('Age of money in days'),
+
+  /** Whether month is deleted */
+  deleted: z.boolean().describe('Deleted flag'),
+
+  /** Array of category data for this month (optional) */
+  categories: z.array(MonthCategorySchema).optional().describe('Categories for this month'),
+});
+
+/**
+ * Schema for summary month data (excludes categories array).
+ *
+ * Used by list_months to return month summaries without category details.
+ */
+export const MonthSummarySchema = z.object({
+  /** Month identifier (YYYY-MM-DD format, first day of month) */
+  month: z.string().describe('Month identifier'),
+
+  /** Optional month note */
+  note: z.string().optional().describe('Month note'),
+
+  /** Total income for the month in dollars */
+  income: z.number().describe('Income in dollars'),
+
+  /** Total budgeted for the month in dollars */
+  budgeted: z.number().describe('Budgeted amount in dollars'),
+
+  /** Total activity (spending) for the month in dollars */
+  activity: z.number().describe('Activity in dollars'),
+
+  /** Amount to be budgeted in dollars */
+  to_be_budgeted: z.number().describe('To be budgeted in dollars'),
+
+  /** Age of money in days (optional, can be null if insufficient history) */
+  age_of_money: z.number().nullish().describe('Age of money in days'),
+
+  /** Whether month is deleted */
+  deleted: z.boolean().describe('Deleted flag'),
+});
+
+/**
+ * Schema for `get_month` tool output.
+ *
+ * Returns detailed month data including categories with cache metadata.
+ */
+export const GetMonthOutputSchema = CacheMetadataSchema.extend({
+  /** Detailed month object including categories */
+  month: MonthDetailSchema.describe('Month details'),
+});
+
+/**
+ * Schema for `list_months` tool output.
+ *
+ * Returns summary of all months without category details.
+ */
+export const ListMonthsOutputSchema = CacheMetadataSchema.extend({
+  /** Array of month summary objects */
+  months: z.array(MonthSummarySchema).describe('List of months'),
+});
+
+// Export inferred TypeScript types
+export type MonthCategory = z.infer<typeof MonthCategorySchema>;
+export type MonthDetail = z.infer<typeof MonthDetailSchema>;
+export type MonthSummary = z.infer<typeof MonthSummarySchema>;
+export type GetMonthOutput = z.infer<typeof GetMonthOutputSchema>;
+export type ListMonthsOutput = z.infer<typeof ListMonthsOutputSchema>;

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

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Output schemas for payee-related tools.
+ *
+ * Defines Zod schemas and TypeScript types for responses from payee tools:
+ * - `list_payees`: Returns all payees with pagination and cache metadata
+ * - `get_payee`: Returns a single payee with cache metadata
+ *
+ * @see src/tools/payeeTools.ts:38-94 for list_payees handler
+ * @see src/tools/payeeTools.ts:100-140 for get_payee handler
+ *
+ * @example
+ * ```typescript
+ * const listOutput: ListPayeesOutput = {
+ *   payees: [
+ *     {
+ *       id: 'payee-123',
+ *       name: 'Whole Foods',
+ *       transfer_account_id: undefined,
+ *       deleted: false
+ *     },
+ *     {
+ *       id: 'payee-456',
+ *       name: 'Transfer: Savings Account',
+ *       transfer_account_id: 'account-789',
+ *       deleted: false
+ *     }
+ *   ],
+ *   total_count: 50,
+ *   returned_count: 50,
+ *   cached: true,
+ *   cache_info: {
+ *     cache_key: 'payees:budget-123',
+ *     age_ms: 10000,
+ *     stale: false
+ *   }
+ * };
+ *
+ * const getOutput: GetPayeeOutput = {
+ *   payee: {
+ *     id: 'payee-123',
+ *     name: 'Whole Foods',
+ *     deleted: false
+ *   },
+ *   cached: false,
+ *   cache_info: {
+ *     cache_key: 'payee:budget-123:payee-123',
+ *     age_ms: 0,
+ *     stale: false
+ *   }
+ * };
+ * ```
+ */
+
+import { z } from 'zod/v4';
+import { CacheMetadataSchema } from '../shared/commonOutputs.js';
+
+/**
+ * Schema for a payee object.
+ *
+ * Represents payee data including transfer account linkage.
+ */
+export const PayeeSchema = z.object({
+  /** Unique identifier for the payee */
+  id: z.string().describe('Payee ID'),
+
+  /** Human-readable payee name */
+  name: z.string().describe('Payee name'),
+
+  /** Transfer account ID if this payee represents a transfer (optional) */
+  transfer_account_id: z.string().optional().describe('Transfer account ID'),
+
+  /** Whether payee is deleted */
+  deleted: z.boolean().describe('Deleted flag'),
+});
+
+/**
+ * Schema for `list_payees` tool output.
+ *
+ * Returns all payees for a budget with pagination and cache metadata.
+ */
+export const ListPayeesOutputSchema = CacheMetadataSchema.extend({
+  /** Array of payee objects */
+  payees: z.array(PayeeSchema).describe('List of payees'),
+
+  /** Total number of payees in budget */
+  total_count: z.number().int().describe('Total payee count'),
+
+  /** Number of payees returned in this response */
+  returned_count: z.number().int().describe('Returned payee count'),
+});
+
+/**
+ * Schema for `get_payee` tool output.
+ *
+ * Returns a single payee by ID with cache metadata.
+ */
+export const GetPayeeOutputSchema = CacheMetadataSchema.extend({
+  /** Single payee object */
+  payee: PayeeSchema.describe('Payee details'),
+});
+
+// Export inferred TypeScript types
+export type Payee = z.infer<typeof PayeeSchema>;
+export type ListPayeesOutput = z.infer<typeof ListPayeesOutputSchema>;
+export type GetPayeeOutput = z.infer<typeof GetPayeeOutputSchema>;