@dizzlkheinz/ynab-mcpb 0.12.1

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

@@ -0,0 +1,333 @@
+/**
+ * Unit tests for utility output schemas
+ *
+ * Tests schema validation for utility tool outputs including:
+ * - SetOutputFormatOutputSchema
+ * - DiagnosticInfoOutputSchema with null cases
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  SetOutputFormatOutputSchema,
+  DiagnosticInfoOutputSchema,
+  EnvironmentInfoSchema,
+  CacheInfoSchema,
+  DeltaInfoSchema,
+} from '../utilityOutputs.js';
+
+describe('SetOutputFormatOutputSchema', () => {
+  it('should validate output with success, message, and options', () => {
+    const validOutput = {
+      success: true,
+      message: 'Output format configured: minify=true, spaces=2',
+      options: {
+        defaultMinify: true,
+        prettySpaces: 2,
+      },
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(validOutput);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(validOutput);
+    }
+  });
+
+  it('should validate output with only defaultMinify option', () => {
+    const validOutput = {
+      success: true,
+      message: 'Output format configured: minify=false',
+      options: {
+        defaultMinify: false,
+      },
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(validOutput);
+    expect(result.success).toBe(true);
+  });
+
+  it('should validate output with only prettySpaces option', () => {
+    const validOutput = {
+      success: true,
+      message: 'Output format configured: spaces=4',
+      options: {
+        prettySpaces: 4,
+      },
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(validOutput);
+    expect(result.success).toBe(true);
+  });
+
+  it('should validate output with empty options', () => {
+    const validOutput = {
+      success: true,
+      message: 'Output format configured',
+      options: {},
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(validOutput);
+    expect(result.success).toBe(true);
+  });
+
+  it('should fail validation when missing required success field', () => {
+    const invalidOutput = {
+      message: 'Output format configured',
+      options: {},
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(invalidOutput);
+    expect(result.success).toBe(false);
+  });
+
+  it('should fail validation when missing required message field', () => {
+    const invalidOutput = {
+      success: true,
+      options: {},
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(invalidOutput);
+    expect(result.success).toBe(false);
+  });
+
+  it('should fail validation when missing required options field', () => {
+    const invalidOutput = {
+      success: true,
+      message: 'Output format configured',
+    };
+
+    const result = SetOutputFormatOutputSchema.safeParse(invalidOutput);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('EnvironmentInfoSchema', () => {
+  it('should validate environment info with null token_preview', () => {
+    const validEnvironment = {
+      token_present: false,
+      token_length: 0,
+      token_preview: null,
+      ynab_env_keys_present: [],
+      working_directory: '/path/to/project',
+    };
+
+    const result = EnvironmentInfoSchema.safeParse(validEnvironment);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.token_preview).toBeNull();
+    }
+  });
+
+  it('should validate environment info with string token_preview', () => {
+    const validEnvironment = {
+      token_present: true,
+      token_length: 64,
+      token_preview: 'abcd...xyz',
+      ynab_env_keys_present: ['YNAB_ACCESS_TOKEN'],
+      working_directory: '/path/to/project',
+    };
+
+    const result = EnvironmentInfoSchema.safeParse(validEnvironment);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.token_preview).toBe('abcd...xyz');
+    }
+  });
+});
+
+describe('CacheInfoSchema', () => {
+  it('should validate cache info with null lastCleanup', () => {
+    const validCache = {
+      entries: 5,
+      estimated_size_kb: 120,
+      keys: ['budgets', 'accounts', 'transactions'],
+      hits: 100,
+      misses: 20,
+      evictions: 2,
+      lastCleanup: null,
+      maxEntries: 1000,
+      hitRate: '83.33%',
+      performance_summary: 'Hit rate: 83.3% (100 hits, 20 misses)',
+    };
+
+    const result = CacheInfoSchema.safeParse(validCache);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.lastCleanup).toBeNull();
+    }
+  });
+
+  it('should validate cache info with string lastCleanup', () => {
+    const validCache = {
+      entries: 5,
+      estimated_size_kb: 120,
+      keys: ['budgets', 'accounts'],
+      hits: 100,
+      misses: 20,
+      evictions: 2,
+      lastCleanup: '2025-01-17T12:00:00.000Z',
+      maxEntries: 1000,
+      hitRate: '83.33%',
+    };
+
+    const result = CacheInfoSchema.safeParse(validCache);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.lastCleanup).toBe('2025-01-17T12:00:00.000Z');
+    }
+  });
+
+  it('should validate cache info without optional performance metrics', () => {
+    const validCache = {
+      entries: 5,
+      estimated_size_kb: 120,
+      keys: ['budgets'],
+    };
+
+    const result = CacheInfoSchema.safeParse(validCache);
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('DeltaInfoSchema', () => {
+  it('should validate delta info with numeric delta_hit_rate', () => {
+    const validDelta = {
+      enabled: true,
+      knowledge_entries: 10,
+      knowledge_stats: { budgets: 3, accounts: 5, transactions: 2 },
+      feature_flag: 'true',
+      delta_hits: 50,
+      delta_misses: 10,
+      delta_hit_rate: 0.8333,
+      merge_operations: 45,
+      knowledge_gap_events: 3,
+    };
+
+    const result = DeltaInfoSchema.safeParse(validDelta);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(typeof result.data.delta_hit_rate).toBe('number');
+      expect(result.data.delta_hit_rate).toBe(0.8333);
+    }
+  });
+
+  it('should fail validation when delta_hit_rate is a string', () => {
+    const invalidDelta = {
+      enabled: true,
+      knowledge_entries: 10,
+      knowledge_stats: {},
+      feature_flag: 'true',
+      delta_hits: 50,
+      delta_misses: 10,
+      delta_hit_rate: '0.8333', // String instead of number
+      merge_operations: 45,
+      knowledge_gap_events: 3,
+    };
+
+    const result = DeltaInfoSchema.safeParse(invalidDelta);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('DiagnosticInfoOutputSchema', () => {
+  it('should validate complete diagnostic output with all null cases', () => {
+    const validDiagnostics = {
+      timestamp: '2025-01-17T12:34:56.789Z',
+      server: {
+        name: 'ynab-mcp-server',
+        version: '0.11.3',
+        node_version: 'v20.10.0',
+        platform: 'linux',
+        arch: 'x64',
+        pid: 12345,
+        uptime_ms: 3600000,
+        uptime_readable: '1h 0m 0s',
+        env: {
+          node_env: 'production',
+          minify_output: 'true',
+        },
+      },
+      memory: {
+        rss_mb: 45.2,
+        heap_used_mb: 32.1,
+        heap_total_mb: 40.0,
+        external_mb: 1.5,
+        array_buffers_mb: 0.8,
+        description: {
+          rss: 'Resident Set Size - total memory allocated for the process',
+          heap_used: 'Used heap memory (objects, closures, etc.)',
+          heap_total: 'Total heap memory allocated',
+          external: 'Memory used by C++ objects bound to JavaScript objects',
+          array_buffers: 'Memory allocated for ArrayBuffer and SharedArrayBuffer',
+        },
+      },
+      environment: {
+        token_present: false,
+        token_length: 0,
+        token_preview: null, // Null case
+        ynab_env_keys_present: [],
+        working_directory: '/path/to/project',
+      },
+      cache: {
+        entries: 5,
+        estimated_size_kb: 120,
+        keys: ['budgets'],
+        hits: 100,
+        misses: 20,
+        evictions: 2,
+        lastCleanup: null, // Null case
+        maxEntries: 1000,
+        hitRate: '83.33%',
+      },
+      delta: {
+        enabled: true,
+        knowledge_entries: 10,
+        knowledge_stats: {},
+        feature_flag: 'true',
+        delta_hits: 50,
+        delta_misses: 10,
+        delta_hit_rate: 0.8333, // Number, not string
+        merge_operations: 45,
+        knowledge_gap_events: 3,
+      },
+    };
+
+    const result = DiagnosticInfoOutputSchema.safeParse(validDiagnostics);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.environment?.token_preview).toBeNull();
+      expect(result.data.cache?.lastCleanup).toBeNull();
+      expect(typeof result.data.delta?.delta_hit_rate).toBe('number');
+    }
+  });
+
+  it('should validate minimal diagnostic output with only timestamp', () => {
+    const validDiagnostics = {
+      timestamp: '2025-01-17T12:34:56.789Z',
+    };
+
+    const result = DiagnosticInfoOutputSchema.safeParse(validDiagnostics);
+    expect(result.success).toBe(true);
+  });
+
+  it('should validate diagnostic output with some optional sections', () => {
+    const validDiagnostics = {
+      timestamp: '2025-01-17T12:34:56.789Z',
+      environment: {
+        token_present: true,
+        token_length: 64,
+        token_preview: 'abcd...xyz',
+        ynab_env_keys_present: ['YNAB_ACCESS_TOKEN'],
+        working_directory: '/path/to/project',
+      },
+      cache: {
+        entries: 0,
+        estimated_size_kb: 0,
+        keys: [],
+      },
+    };
+
+    const result = DiagnosticInfoOutputSchema.safeParse(validDiagnostics);
+    expect(result.success).toBe(true);
+  });
+});

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

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Output schemas for account-related tools.
+ *
+ * Defines Zod schemas and TypeScript types for responses from account tools:
+ * - `list_accounts`: Returns all accounts with pagination and cache metadata
+ * - `get_account`: Returns a single account with cache metadata
+ *
+ * @see src/tools/accountTools.ts:64-128 for list_accounts handler
+ * @see src/tools/accountTools.ts:134-190 for get_account handler
+ *
+ * @example
+ * ```typescript
+ * const listOutput: ListAccountsOutput = {
+ *   accounts: [
+ *     {
+ *       id: 'account-123',
+ *       name: 'Checking Account',
+ *       type: 'checking',
+ *       on_budget: true,
+ *       closed: false,
+ *       note: 'Main checking account',
+ *       balance: 2500.50,
+ *       cleared_balance: 2400.00,
+ *       uncleared_balance: 100.50,
+ *       transfer_payee_id: 'payee-456',
+ *       direct_import_linked: true,
+ *       direct_import_in_error: false
+ *     }
+ *   ],
+ *   total_count: 5,
+ *   returned_count: 5,
+ *   cached: true,
+ *   cache_info: {
+ *     cache_key: 'accounts:budget-123',
+ *     age_ms: 3000,
+ *     stale: false
+ *   }
+ * };
+ *
+ * const getOutput: GetAccountOutput = {
+ *   account: {
+ *     id: 'account-123',
+ *     name: 'Checking Account',
+ *     type: 'checking',
+ *     on_budget: true,
+ *     closed: false,
+ *     balance: 2500.50,
+ *     cleared_balance: 2400.00,
+ *     uncleared_balance: 100.50,
+ *     transfer_payee_id: 'payee-456'
+ *   },
+ *   cached: false,
+ *   cache_info: {
+ *     cache_key: 'account:budget-123:account-123',
+ *     age_ms: 0,
+ *     stale: false
+ *   }
+ * };
+ * ```
+ */
+
+import { z } from 'zod/v4';
+import { CacheMetadataSchema } from '../shared/commonOutputs.js';
+
+/**
+ * Schema for an account object.
+ *
+ * Represents account data with balances in dollars (converted from YNAB milliunits).
+ */
+export const AccountSchema = z.object({
+  /** Unique identifier for the account */
+  id: z.string().describe('Account ID'),
+
+  /** Human-readable account name */
+  name: z.string().describe('Account name'),
+
+  /** Account type (checking, savings, creditCard, etc.) */
+  type: z.string().describe('Account type'),
+
+  /** Whether account is on-budget or tracking */
+  on_budget: z.boolean().describe('On-budget flag'),
+
+  /** Whether account is closed */
+  closed: z.boolean().describe('Closed flag'),
+
+  /** Optional account note */
+  note: z.string().optional().describe('Account note'),
+
+  /** Current account balance in dollars */
+  balance: z.number().describe('Account balance in dollars'),
+
+  /** Cleared balance in dollars */
+  cleared_balance: z.number().describe('Cleared balance in dollars'),
+
+  /** Uncleared balance in dollars */
+  uncleared_balance: z.number().describe('Uncleared balance in dollars'),
+
+  /** Payee ID for transfers to this account */
+  transfer_payee_id: z.string().describe('Transfer payee ID'),
+
+  /** Whether account is linked for direct import (optional) */
+  direct_import_linked: z.boolean().optional().describe('Direct import linked flag'),
+
+  /** Whether direct import is in error state (optional) */
+  direct_import_in_error: z.boolean().optional().describe('Direct import error flag'),
+});
+
+/**
+ * Schema for `list_accounts` tool output.
+ *
+ * Returns all accounts for a budget with pagination and cache metadata.
+ */
+export const ListAccountsOutputSchema = CacheMetadataSchema.extend({
+  /** Array of account objects */
+  accounts: z.array(AccountSchema).describe('List of accounts'),
+
+  /** Total number of accounts in budget */
+  total_count: z.number().int().describe('Total account count'),
+
+  /** Number of accounts returned in this response */
+  returned_count: z.number().int().describe('Returned account count'),
+});
+
+/**
+ * Schema for `get_account` tool output.
+ *
+ * Returns a single account by ID with cache metadata.
+ */
+export const GetAccountOutputSchema = CacheMetadataSchema.extend({
+  /** Single account object */
+  account: AccountSchema.describe('Account details'),
+});
+
+// Export inferred TypeScript types
+export type Account = z.infer<typeof AccountSchema>;
+export type ListAccountsOutput = z.infer<typeof ListAccountsOutputSchema>;
+export type GetAccountOutput = z.infer<typeof GetAccountOutputSchema>;

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

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Output schemas for budget-related tools.
+ *
+ * Defines Zod schemas and TypeScript types for responses from budget tools:
+ * - `list_budgets`: Returns all budgets with metadata
+ *
+ * @see src/tools/budgetTools.ts:24-67 for handler implementation
+ *
+ * @example
+ * ```typescript
+ * const output: ListBudgetsOutput = {
+ *   budgets: [
+ *     {
+ *       id: 'budget-123',
+ *       name: 'My Budget',
+ *       last_modified_on: '2025-11-17T10:30:00Z',
+ *       first_month: '2024-01-01',
+ *       last_month: '2025-11-01',
+ *       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
+ *       }
+ *     }
+ *   ],
+ *   cached: true,
+ *   cache_info: {
+ *     cache_key: 'budgets:all',
+ *     age_ms: 1200,
+ *     stale: false
+ *   }
+ * };
+ * ```
+ */
+
+import { z } from 'zod/v4';
+import { CacheMetadataSchema } from '../shared/commonOutputs.js';
+import { DateFormatSchema, CurrencyFormatSchema } from './utilityOutputs.js';
+
+/**
+ * Schema for a budget summary object.
+ *
+ * Represents basic budget metadata returned by YNAB API.
+ */
+export const BudgetSummarySchema = z.object({
+  /** Unique identifier for the budget */
+  id: z.string().describe('Budget ID'),
+
+  /** Human-readable budget name */
+  name: z.string().describe('Budget name'),
+
+  /** ISO 8601 timestamp of last modification (optional) */
+  last_modified_on: z.string().optional().describe('Last modification timestamp'),
+
+  /** First month in budget (YYYY-MM-DD format, optional) */
+  first_month: z.string().optional().describe('First month in budget'),
+
+  /** Last month in budget (YYYY-MM-DD format, optional) */
+  last_month: z.string().optional().describe('Last month in budget'),
+
+  /** Date format settings for this budget (optional) */
+  date_format: DateFormatSchema.optional().describe('Date format settings'),
+
+  /** Currency format settings for this budget (optional) */
+  currency_format: CurrencyFormatSchema.optional().describe('Currency format settings'),
+});
+
+/**
+ * Schema for `list_budgets` tool output.
+ *
+ * Returns all budgets accessible to the user with cache metadata.
+ */
+export const ListBudgetsOutputSchema = CacheMetadataSchema.extend({
+  /** Array of budget summaries */
+  budgets: z.array(BudgetSummarySchema).describe('List of budgets'),
+});
+
+// Export inferred TypeScript types
+export type BudgetSummary = z.infer<typeof BudgetSummarySchema>;
+export type ListBudgetsOutput = z.infer<typeof ListBudgetsOutputSchema>;