@dizzlkheinz/ynab-mcpb 0.12.1

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

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview Output schemas for transaction-related tools.
+ *
+ * Defines Zod schemas and TypeScript types for responses from transaction tools:
+ * - `list_transactions`: Returns transactions with two modes (normal and preview for large responses)
+ * - `get_transaction`: Returns a single transaction with cache metadata
+ *
+ * The list_transactions tool implements special handling for large responses:
+ * - Normal mode: Returns all transactions with cache metadata
+ * - Preview mode: Returns a preview of first 10 transactions when count > 100
+ *
+ * @see src/tools/transactionTools.ts:745-864 for list_transactions handler
+ * @see src/tools/transactionTools.ts:870-944 for get_transaction handler
+ *
+ * @example
+ * ```typescript
+ * // Normal mode (count <= 100)
+ * const listOutput: ListTransactionsOutput = {
+ *   total_count: 50,
+ *   cached: true,
+ *   cache_info: {
+ *     cache_key: 'transactions:budget-123:2025-11-01',
+ *     age_ms: 2000,
+ *     stale: false
+ *   },
+ *   transactions: [
+ *     {
+ *       id: 'txn-123',
+ *       date: '2025-11-17',
+ *       amount: -45.50,
+ *       memo: 'Grocery shopping',
+ *       cleared: 'cleared',
+ *       approved: true,
+ *       flag_color: 'red',
+ *       account_id: 'account-123',
+ *       payee_id: 'payee-456',
+ *       category_id: 'category-789',
+ *       deleted: false,
+ *       account_name: 'Checking',
+ *       payee_name: 'Whole Foods',
+ *       category_name: 'Groceries'
+ *     }
+ *   ]
+ * };
+ *
+ * // Preview mode (count > 100)
+ * const previewOutput: ListTransactionsOutput = {
+ *   message: 'Large result set detected',
+ *   suggestion: 'Use filter parameters to narrow results',
+ *   showing: 'First 50 transactions:',
+ *   total_count: 250,
+ *   estimated_size_kb: 150,
+ *   preview_transactions: [
+ *     {
+ *       id: 'txn-123',
+ *       date: '2025-11-17',
+ *       amount: -45.50,
+ *       memo: 'Grocery shopping',
+ *       payee_name: 'Whole Foods',
+ *       category_name: 'Groceries'
+ *     }
+ *   ]
+ * };
+ *
+ * // Get single transaction
+ * const getOutput: GetTransactionOutput = {
+ *   transaction: {
+ *     id: 'txn-123',
+ *     date: '2025-11-17',
+ *     amount: -45.50,
+ *     memo: 'Grocery shopping',
+ *     cleared: 'cleared',
+ *     approved: true,
+ *     account_id: 'account-123',
+ *     payee_id: 'payee-456',
+ *     category_id: 'category-789',
+ *     deleted: false,
+ *     account_name: 'Checking',
+ *     payee_name: 'Whole Foods',
+ *     category_name: 'Groceries'
+ *   },
+ *   cached: false,
+ *   cache_info: {
+ *     cache_key: 'transaction:budget-123:txn-123',
+ *     age_ms: 0,
+ *     stale: false
+ *   }
+ * };
+ * ```
+ */
+
+import { z } from 'zod/v4';
+import { CacheMetadataSchema } from '../shared/commonOutputs.js';
+
+/**
+ * Schema for a complete transaction object.
+ *
+ * Represents full transaction data with amounts in dollars (converted from YNAB milliunits).
+ */
+export const TransactionSchema = z.object({
+  /** Unique identifier for the transaction */
+  id: z.string().describe('Transaction ID'),
+
+  /** Transaction date (YYYY-MM-DD format) */
+  date: z.string().describe('Transaction date'),
+
+  /** Transaction amount in dollars (negative for outflows, positive for inflows) */
+  amount: z.number().describe('Transaction amount in dollars'),
+
+  /** Optional transaction memo */
+  memo: z.string().optional().describe('Transaction memo'),
+
+  /** Cleared status (uncleared, cleared, reconciled) */
+  cleared: z.string().describe('Cleared status'),
+
+  /** Whether transaction is approved */
+  approved: z.boolean().describe('Approved flag'),
+
+  /** Optional flag color */
+  flag_color: z.string().optional().describe('Flag color'),
+
+  /** Account ID for this transaction */
+  account_id: z.string().describe('Account ID'),
+
+  /** Optional payee ID */
+  payee_id: z.string().nullish().describe('Payee ID'),
+
+  /** Optional category ID */
+  category_id: z.string().nullish().describe('Category ID'),
+
+  /** Optional transfer account ID (for transfer transactions) */
+  transfer_account_id: z.string().nullish().describe('Transfer account ID'),
+
+  /** Optional transfer transaction ID (for transfer transactions) */
+  transfer_transaction_id: z.string().nullish().describe('Transfer transaction ID'),
+
+  /** Optional matched transaction ID (for imported transactions) */
+  matched_transaction_id: z.string().nullish().describe('Matched transaction ID'),
+
+  /** Optional import ID */
+  import_id: z.string().optional().describe('Import ID'),
+
+  /** Whether transaction is deleted */
+  deleted: z.boolean().describe('Deleted flag'),
+
+  /** Account name (enriched field, optional) */
+  account_name: z.string().optional().describe('Account name'),
+
+  /** Payee name (enriched field, optional) */
+  payee_name: z.string().optional().describe('Payee name'),
+
+  /** Category name (enriched field, optional) */
+  category_name: z.string().optional().describe('Category name'),
+});
+
+/**
+ * Schema for a transaction preview object.
+ *
+ * Subset of transaction fields shown in preview mode for large result sets.
+ */
+export const TransactionPreviewSchema = z.object({
+  /** Unique identifier for the transaction */
+  id: z.string().describe('Transaction ID'),
+
+  /** Transaction date (YYYY-MM-DD format) */
+  date: z.string().describe('Transaction date'),
+
+  /** Transaction amount in dollars */
+  amount: z.number().describe('Transaction amount in dollars'),
+
+  /** Optional transaction memo */
+  memo: z.string().optional().describe('Transaction memo'),
+
+  /** Payee name (enriched field, optional) */
+  payee_name: z.string().optional().describe('Payee name'),
+
+  /** Category name (enriched field, optional) */
+  category_name: z.string().optional().describe('Category name'),
+});
+
+/**
+ * Schema for `list_transactions` tool output (normal mode).
+ *
+ * Returns all transactions when count <= 100.
+ */
+const ListTransactionsNormalSchema = CacheMetadataSchema.extend({
+  /** Total number of transactions */
+  total_count: z.number().int().describe('Total transaction count'),
+
+  /** Array of complete transaction objects */
+  transactions: z.array(TransactionSchema).describe('List of transactions'),
+});
+
+/**
+ * Schema for `list_transactions` tool output (preview mode).
+ *
+ * Returns a preview when count > 100 to avoid overwhelming responses.
+ */
+const ListTransactionsPreviewSchema = z.object({
+  /** Message explaining large result set */
+  message: z.string().describe('Large result set message'),
+
+  /** Suggestion to narrow results */
+  suggestion: z.string().describe('Suggestion to narrow results'),
+
+  /** Human-readable summary of transactions shown in preview (e.g., "First 50 transactions:") */
+  showing: z.string().describe('Human-readable summary of transactions shown'),
+
+  /** Total number of transactions */
+  total_count: z.number().int().describe('Total transaction count'),
+
+  /** Estimated response size in KB if all transactions returned */
+  estimated_size_kb: z.number().describe('Estimated response size in KB'),
+
+  /** Array of preview transaction objects */
+  preview_transactions: z.array(TransactionPreviewSchema).describe('Preview transactions'),
+});
+
+/**
+ * Schema for `list_transactions` tool output.
+ *
+ * Discriminated union supporting both normal and preview response modes.
+ */
+export const ListTransactionsOutputSchema = z.union([
+  ListTransactionsNormalSchema,
+  ListTransactionsPreviewSchema,
+]);
+
+/**
+ * Schema for `get_transaction` tool output.
+ *
+ * Returns a single transaction by ID with cache metadata.
+ */
+export const GetTransactionOutputSchema = CacheMetadataSchema.extend({
+  /** Single transaction object */
+  transaction: TransactionSchema.describe('Transaction details'),
+});
+
+// Export inferred TypeScript types
+export type Transaction = z.infer<typeof TransactionSchema>;
+export type TransactionPreview = z.infer<typeof TransactionPreviewSchema>;
+export type ListTransactionsOutput = z.infer<typeof ListTransactionsOutputSchema>;
+export type GetTransactionOutput = z.infer<typeof GetTransactionOutputSchema>;

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

@@ -0,0 +1,411 @@
+/**
+ * @fileoverview Output schemas for utility tools
+ *
+ * This file contains comprehensive Zod schemas for validating the output
+ * of utility tools including user info, amount conversion, budget defaults,
+ * cache management, output formatting, and diagnostic information.
+ *
+ * All schemas include TypeScript type inference for type-safe usage throughout
+ * the codebase. Reference the corresponding handler implementations for
+ * exact response shape details.
+ */
+
+import { z } from 'zod/v4';
+import { SuccessResponseSchema } from '../shared/commonOutputs.js';
+
+// ============================================================================
+// GET USER OUTPUT
+// ============================================================================
+
+/**
+ * Schema for YNAB user object
+ *
+ * Represents the authenticated user's information from YNAB API.
+ */
+export const UserSchema = z.object({
+  id: z.string(),
+});
+
+/**
+ * Output schema for get_user tool
+ *
+ * Returns information about the authenticated YNAB user.
+ *
+ * @see src/tools/utilityTools.ts:23-45 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: GetUserOutput = {
+ *   user: { id: "abc123" }
+ * };
+ * ```
+ */
+export const GetUserOutputSchema = z.object({
+  user: UserSchema,
+});
+
+export type GetUserOutput = z.infer<typeof GetUserOutputSchema>;
+
+// ============================================================================
+// CONVERT AMOUNT OUTPUT
+// ============================================================================
+
+/**
+ * Schema for amount conversion details
+ *
+ * Contains the conversion result between dollars and YNAB milliunits.
+ */
+export const ConversionSchema = z.object({
+  original_amount: z.number(),
+  converted_amount: z.number(),
+  to_milliunits: z.boolean(),
+  description: z.string(),
+});
+
+/**
+ * Output schema for convert_amount tool
+ *
+ * Converts between dollars and YNAB milliunits (1 dollar = 1000 milliunits).
+ *
+ * @see src/tools/utilityTools.ts:51-90 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: ConvertAmountOutput = {
+ *   conversion: {
+ *     original_amount: 25.50,
+ *     converted_amount: 25500,
+ *     to_milliunits: true,
+ *     description: "$25.50 converted to 25500 milliunits"
+ *   }
+ * };
+ * ```
+ */
+export const ConvertAmountOutputSchema = z.object({
+  conversion: ConversionSchema,
+});
+
+export type ConvertAmountOutput = z.infer<typeof ConvertAmountOutputSchema>;
+
+// ============================================================================
+// GET DEFAULT BUDGET OUTPUT
+// ============================================================================
+
+/**
+ * Output schema for get_default_budget tool
+ *
+ * Returns the currently configured default budget ID (if any).
+ *
+ * @see src/server/YNABMCPServer.ts:474-510 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: GetDefaultBudgetOutput = {
+ *   default_budget_id: "abc123",
+ *   has_default: true,
+ *   message: "Default budget ID: abc123"
+ * };
+ * ```
+ */
+export const GetDefaultBudgetOutputSchema = z.object({
+  default_budget_id: z.string().nullable(),
+  has_default: z.boolean(),
+  message: z.string(),
+});
+
+export type GetDefaultBudgetOutput = z.infer<typeof GetDefaultBudgetOutputSchema>;
+
+// ============================================================================
+// SET DEFAULT BUDGET OUTPUT
+// ============================================================================
+
+/**
+ * Output schema for set_default_budget tool
+ *
+ * Confirms the default budget has been set and indicates whether cache warming started.
+ *
+ * @see src/server/YNABMCPServer.ts:437-471 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: SetDefaultBudgetOutput = {
+ *   success: true,
+ *   message: "Default budget set to 'My Budget' and cache warming started",
+ *   default_budget_id: "abc123",
+ *   cache_warm_started: true
+ * };
+ * ```
+ */
+export const SetDefaultBudgetOutputSchema = SuccessResponseSchema.extend({
+  default_budget_id: z.string(),
+  cache_warm_started: z.boolean(),
+});
+
+export type SetDefaultBudgetOutput = z.infer<typeof SetDefaultBudgetOutputSchema>;
+
+// ============================================================================
+// CLEAR CACHE OUTPUT
+// ============================================================================
+
+/**
+ * Output schema for clear_cache tool
+ *
+ * Simple success confirmation for cache clearing operation.
+ *
+ * @see src/server/YNABMCPServer.ts:852-868 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: ClearCacheOutput = {
+ *   success: true
+ * };
+ * ```
+ */
+export const ClearCacheOutputSchema = SuccessResponseSchema.pick({ success: true });
+
+export type ClearCacheOutput = z.infer<typeof ClearCacheOutputSchema>;
+
+// ============================================================================
+// SET OUTPUT FORMAT OUTPUT
+// ============================================================================
+
+/**
+ * Output schema for set_output_format tool
+ *
+ * Confirms output format settings have been updated.
+ *
+ * @see src/server/YNABMCPServer.ts:870-898 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: SetOutputFormatOutput = {
+ *   success: true,
+ *   message: "Output format configured: minify=true, spaces=2",
+ *   options: { defaultMinify: true, prettySpaces: 2 }
+ * };
+ * ```
+ */
+export const SetOutputFormatOutputSchema = SuccessResponseSchema.extend({
+  options: z.object({
+    defaultMinify: z.boolean().optional(),
+    prettySpaces: z.number().optional(),
+  }),
+});
+
+export type SetOutputFormatOutput = z.infer<typeof SetOutputFormatOutputSchema>;
+
+// ============================================================================
+// DIAGNOSTIC INFO OUTPUT
+// ============================================================================
+
+/**
+ * Schema for server diagnostic information
+ *
+ * Contains runtime information about the MCP server process.
+ */
+export const ServerInfoSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  node_version: z.string(),
+  platform: z.string(),
+  arch: z.string(),
+  pid: z.number(),
+  uptime_ms: z.number(),
+  uptime_readable: z.string(),
+  env: z.record(z.string(), z.unknown()),
+});
+
+/**
+ * Schema for memory usage information
+ *
+ * Reports memory consumption of the MCP server process.
+ */
+export const MemoryInfoSchema = z.object({
+  rss_mb: z.number(),
+  heap_used_mb: z.number(),
+  heap_total_mb: z.number(),
+  external_mb: z.number(),
+  array_buffers_mb: z.number(),
+  description: z.record(z.string(), z.string()),
+});
+
+/**
+ * Schema for environment configuration information
+ *
+ * Shows environment variable configuration status.
+ */
+export const EnvironmentInfoSchema = z.object({
+  token_present: z.boolean(),
+  token_length: z.number(),
+  token_preview: z.string().nullable(),
+  ynab_env_keys_present: z.array(z.string()),
+  working_directory: z.string(),
+});
+
+/**
+ * Schema for cache diagnostic information
+ *
+ * Reports cache status and performance metrics.
+ */
+export const CacheInfoSchema = z.object({
+  entries: z.number(),
+  estimated_size_kb: z.number(),
+  keys: z.array(z.string()),
+  // Optional performance metrics
+  hits: z.number().optional(),
+  misses: z.number().optional(),
+  evictions: z.number().optional(),
+  lastCleanup: z.string().nullable().optional(),
+  maxEntries: z.number().optional(),
+  hitRate: z.string().optional(),
+  performance_summary: z.string().optional(),
+});
+
+/**
+ * Schema for delta request optimization information
+ *
+ * Reports status of delta request feature and knowledge base.
+ */
+export const DeltaInfoSchema = z.object({
+  enabled: z.boolean(),
+  knowledge_entries: z.number(),
+  knowledge_stats: z.record(z.string(), z.unknown()),
+  feature_flag: z.string(),
+  delta_hits: z.number(),
+  delta_misses: z.number(),
+  delta_hit_rate: z.number(),
+  merge_operations: z.number(),
+  knowledge_gap_events: z.number(),
+});
+
+/**
+ * Output schema for diagnostic_info tool
+ *
+ * Returns comprehensive diagnostic information about the MCP server,
+ * including runtime info, memory usage, environment configuration,
+ * cache status, and delta request optimization metrics.
+ *
+ * @see src/server/diagnostics.ts:181-337 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: DiagnosticInfoOutput = {
+ *   timestamp: "2025-01-17T12:34:56.789Z",
+ *   server: {
+ *     name: "ynab-mcp-server",
+ *     version: "0.12.0",
+ *     node_version: "v20.10.0",
+ *     // ... other server info
+ *   },
+ *   memory: {
+ *     rss_mb: 45.2,
+ *     heap_used_mb: 32.1,
+ *     // ... other memory info
+ *   },
+ *   // ... other diagnostic sections
+ * };
+ * ```
+ */
+export const DiagnosticInfoOutputSchema = z.object({
+  timestamp: z.string(),
+  server: ServerInfoSchema.optional(),
+  memory: MemoryInfoSchema.optional(),
+  environment: EnvironmentInfoSchema.optional(),
+  cache: CacheInfoSchema.optional(),
+  delta: DeltaInfoSchema.optional(),
+});
+
+export type DiagnosticInfoOutput = z.infer<typeof DiagnosticInfoOutputSchema>;
+
+// ============================================================================
+// GET BUDGET OUTPUT
+// ============================================================================
+
+/**
+ * Schema for YNAB date format configuration
+ *
+ * Represents how dates are formatted in the YNAB budget.
+ */
+export const DateFormatSchema = z.object({
+  format: z.string(),
+});
+
+/**
+ * Schema for YNAB currency format configuration
+ *
+ * Represents how currency values are formatted in the YNAB budget.
+ */
+export const CurrencyFormatSchema = z.object({
+  iso_code: z.string(),
+  example_format: z.string(),
+  decimal_digits: z.number(),
+  decimal_separator: z.string().optional(),
+  symbol_first: z.boolean().optional(),
+  group_separator: z.string().optional(),
+  currency_symbol: z.string().optional(),
+  display_symbol: z.boolean().optional(),
+});
+
+/**
+ * Schema for detailed budget information
+ *
+ * Contains comprehensive details about a YNAB budget including
+ * format settings and entity counts.
+ */
+export const BudgetDetailSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  last_modified_on: z.string().optional(),
+  first_month: z.string().optional(),
+  last_month: z.string().optional(),
+  date_format: DateFormatSchema.optional(),
+  currency_format: CurrencyFormatSchema.optional(),
+  accounts_count: z.number(),
+  categories_count: z.number(),
+  payees_count: z.number(),
+  months_count: z.number(),
+  message: z.string(),
+});
+
+/**
+ * Output schema for get_budget tool
+ *
+ * Returns detailed information about a specific budget including
+ * format settings, date ranges, and counts of budget entities.
+ *
+ * @see src/tools/budgetTools.ts:73-112 - Handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: GetBudgetOutput = {
+ *   budget: {
+ *     id: "abc123",
+ *     name: "My Budget",
+ *     last_modified_on: "2025-01-17T12:00:00Z",
+ *     first_month: "2024-01",
+ *     last_month: "2025-12",
+ *     date_format: { format: "MM/DD/YYYY" },
+ *     currency_format: {
+ *       iso_code: "USD",
+ *       example_format: "$1,234.56",
+ *       decimal_digits: 2,
+ *       decimal_separator: ".",
+ *       symbol_first: true,
+ *       group_separator: ",",
+ *       currency_symbol: "$",
+ *       display_symbol: true
+ *     },
+ *     accounts_count: 5,
+ *     categories_count: 25,
+ *     payees_count: 100,
+ *     months_count: 24,
+ *     message: "Budget 'My Budget' retrieved successfully"
+ *   }
+ * };
+ * ```
+ */
+export const GetBudgetOutputSchema = z.object({
+  budget: BudgetDetailSchema,
+});
+
+export type GetBudgetOutput = z.infer<typeof GetBudgetOutputSchema>;