@dizzlkheinz/ynab-mcpb 0.12.1

package/src/utils/dateUtils.ts

@@ -0,0 +1,108 @@
+/**
+ * Unified date utilities for YNAB MCP Server
+ *
+ * All date formatting should use these utilities to ensure consistency
+ * and prevent bugs like the duplicate month issue.
+ *
+ * Uses date-fns internally for robust date operations while providing
+ * YNAB-specific business logic.
+ */
+
+import { format, subMonths, isValid, parse } from 'date-fns';
+
+/**
+ * Formats a date as YYYY-MM-01 (YNAB month format)
+ * @param date The date to format
+ * @returns Formatted date string in YYYY-MM-01 format
+ */
+export function formatYNABMonth(date: Date): string {
+  return format(date, "yyyy-MM-'01'");
+}
+
+/**
+ * Formats a date as YYYY-MM-DD (ISO date format)
+ * @param date The date to format
+ * @returns Formatted date string in YYYY-MM-DD format
+ */
+export function formatISODate(date: Date): string {
+  return format(date, 'yyyy-MM-dd');
+}
+
+/**
+ * Gets the current month in YNAB format (YYYY-MM-01)
+ * @returns Current month formatted as YYYY-MM-01
+ */
+export function getCurrentMonth(): string {
+  return formatYNABMonth(new Date());
+}
+
+/**
+ * Gets today's date in ISO format (YYYY-MM-DD)
+ * @returns Today's date formatted as YYYY-MM-DD
+ */
+export function getToday(): string {
+  return formatISODate(new Date());
+}
+
+/**
+ * Generates an array of historical months going backwards from a start date
+ * @param monthCount Number of months to generate
+ * @param startDate The starting date (defaults to current date)
+ * @returns Array of month strings in YYYY-MM-01 format, ordered newest to oldest
+ */
+export function getHistoricalMonths(monthCount: number, startDate?: Date): string[] {
+  const baseDate = startDate || new Date();
+
+  return Array.from({ length: monthCount }, (_, i) => {
+    const date = subMonths(baseDate, i);
+    return formatYNABMonth(date);
+  });
+}
+
+/**
+ * Subtracts months from a date
+ * @param date The base date
+ * @param months Number of months to subtract
+ * @returns New date with months subtracted
+ */
+export function subtractMonths(date: Date, months: number): Date {
+  return subMonths(date, months);
+}
+
+/**
+ * Validates if a string is in YYYY-MM-DD format
+ * @param dateString The string to validate
+ * @returns True if valid ISO date format
+ */
+export function isValidISODate(dateString: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
+    return false;
+  }
+  const parsed = parse(dateString, 'yyyy-MM-dd', new Date());
+  return isValid(parsed);
+}
+
+/**
+ * Validates if a string is in YYYY-MM-01 format (YNAB month format)
+ * @param monthString The string to validate
+ * @returns True if valid YNAB month format
+ */
+export function isValidYNABMonth(monthString: string): boolean {
+  if (!/^\d{4}-\d{2}-01$/.test(monthString)) {
+    return false;
+  }
+  const parsed = parse(monthString, "yyyy-MM-'01'", new Date());
+  return isValid(parsed);
+}
+
+/**
+ * Converts a YYYY-MM format to YYYY-MM-01 format
+ * @param yearMonth String in YYYY-MM format
+ * @returns String in YYYY-MM-01 format
+ */
+export function yearMonthToYNABMonth(yearMonth: string): string {
+  if (!/^\d{4}-\d{2}$/.test(yearMonth)) {
+    throw new Error('Invalid year-month format. Expected YYYY-MM');
+  }
+  return `${yearMonth}-01`;
+}

package/src/utils/money.ts

@@ -0,0 +1,123 @@
+// money.ts
+import * as ynab from 'ynab';
+
+export type Milli = number; // integer milliunits (no bigint)
+
+export type MoneyDirection = 'credit' | 'debit' | 'balanced';
+
+export interface MoneyValue {
+  value_milliunits: Milli;
+  value: number;
+  value_display: string;
+  currency: string;
+  direction: MoneyDirection;
+}
+
+const DEFAULT_CURRENCY = 'USD';
+const DEFAULT_DECIMAL_DIGITS = 2;
+
+/**
+ * Extract decimal digits from YNAB CurrencyFormat
+ */
+export const getDecimalDigits = (
+  currencyFormat: ynab.CurrencyFormat | null | undefined,
+): number => {
+  return currencyFormat?.decimal_digits ?? DEFAULT_DECIMAL_DIGITS;
+};
+
+/**
+ * Extract ISO currency code from YNAB CurrencyFormat
+ */
+export const getCurrencyCode = (currencyFormat: ynab.CurrencyFormat | null | undefined): string => {
+  return currencyFormat?.iso_code ?? DEFAULT_CURRENCY;
+};
+
+export const toMilli = (x: number | string): Milli => {
+  const n = Number(x);
+  const m = Math.round(n * 1000);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(m)) {
+    throw new Error(`Invalid/unsafe amount: ${x}`);
+  }
+  return m;
+};
+
+/**
+ * Convert milliunits to currency amount using proper decimal digits
+ * Uses YNAB SDK's conversion logic which handles different currency formats
+ * @param m - Milliunits value
+ * @param decimalDigits - Number of decimal digits for the currency (default: 2 for USD/EUR, 0 for JPY, 3 for BHD, etc.)
+ */
+export const fromMilli = (m: Milli, decimalDigits: number = DEFAULT_DECIMAL_DIGITS): number => {
+  return ynab.utils.convertMilliUnitsToCurrencyAmount(m, decimalDigits);
+};
+
+export const assertMilli = (m: number, msg = 'Expected safe integer milliunits') => {
+  if (!Number.isSafeInteger(m)) throw new Error(msg);
+};
+
+export const addMilli = (a: Milli, b: Milli): Milli => {
+  const s = a + b;
+  if (!Number.isSafeInteger(s)) throw new Error('Milliunit sum overflow');
+  return s;
+};
+
+export const inWindow = (
+  iso: string,
+  start: string | undefined = undefined,
+  end: string | undefined = undefined,
+) => (!start || iso >= start) && (!end || iso <= end);
+
+export const moneyDirection = (value: Milli): MoneyDirection => {
+  if (value === 0) return 'balanced';
+  return value > 0 ? 'credit' : 'debit';
+};
+
+const makeFormatter = (currency: string, decimalDigits: number = DEFAULT_DECIMAL_DIGITS) =>
+  new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: decimalDigits,
+    maximumFractionDigits: decimalDigits,
+  });
+
+/**
+ * Format milliunits as currency string with proper decimal digits
+ * @param value - Milliunits value
+ * @param currency - ISO currency code (default: USD)
+ * @param decimalDigits - Number of decimal digits (default: 2)
+ */
+export const formatMoney = (
+  value: Milli,
+  currency: string = DEFAULT_CURRENCY,
+  decimalDigits: number = DEFAULT_DECIMAL_DIGITS,
+): string => makeFormatter(currency, decimalDigits).format(fromMilli(value, decimalDigits));
+
+/**
+ * Convert milliunits to MoneyValue with proper currency format
+ * @param value - Milliunits value
+ * @param currency - ISO currency code (default: USD)
+ * @param decimalDigits - Number of decimal digits (default: 2)
+ */
+export const toMoneyValue = (
+  value: Milli,
+  currency: string = DEFAULT_CURRENCY,
+  decimalDigits: number = DEFAULT_DECIMAL_DIGITS,
+): MoneyValue => ({
+  value_milliunits: value,
+  value: fromMilli(value, decimalDigits),
+  value_display: formatMoney(value, currency, decimalDigits),
+  currency,
+  direction: moneyDirection(value),
+});
+
+/**
+ * Convert decimal amount to MoneyValue
+ * @param amount - Decimal amount
+ * @param currency - ISO currency code (default: USD)
+ * @param decimalDigits - Number of decimal digits (default: 2)
+ */
+export const toMoneyValueFromDecimal = (
+  amount: number,
+  currency: string = DEFAULT_CURRENCY,
+  decimalDigits: number = DEFAULT_DECIMAL_DIGITS,
+): MoneyValue => toMoneyValue(toMilli(amount), currency, decimalDigits);

package/test-csv-sample.csv

@@ -0,0 +1,28 @@
+Date,Description,Amount,Balance
+2024-01-15,"GROCERY STORE PURCHASE",-45.67,1234.56
+2024-01-16,"PAYCHECK DEPOSIT",2500.00,3734.56
+2024-01-17,"COFFEE SHOP",-4.25,3730.31
+2024-01-18,"ATM WITHDRAWAL",-60.00,3670.31
+2024-01-19,"ONLINE PURCHASE - AMAZON",-23.45,3646.86
+2024-01-20,"RESTAURANT DINNER",-78.90,3567.96
+2024-01-22,"GAS STATION",-52.34,3515.62
+2024-01-23,"PHARMACY",-12.67,3502.95
+2024-01-24,"UTILITY PAYMENT",-125.00,3377.95
+2024-01-25,"GROCERY STORE PURCHASE",-67.89,3310.06
+2024-01-26,"MOBILE PHONE BILL",-85.00,3225.06
+2024-01-29,"RESTAURANT LUNCH",-18.45,3206.61
+2024-01-30,"BANK INTEREST EARNED",2.15,3208.76
+2024-01-31,"MONTHLY RENT",-1200.00,2008.76
+2024-02-01,"COFFEE SHOP",-4.75,2004.01
+2024-02-02,"GROCERY STORE PURCHASE",-89.23,1914.78
+2024-02-03,"MOVIE THEATER",-24.00,1890.78
+2024-02-05,"ONLINE SUBSCRIPTION",-9.99,1880.79
+2024-02-06,"RESTAURANT DINNER",-56.78,1823.01
+2024-02-07,"GAS STATION",-48.90,1774.11
+2024-02-08,"PHARMACY",-15.67,1758.44
+2024-02-09,"GROCERY STORE PURCHASE",-34.56,1723.88
+2024-02-12,"PAYCHECK DEPOSIT",2500.00,4223.88
+2024-02-13,"INSURANCE PAYMENT",-150.00,4073.88
+2024-02-14,"RESTAURANT VALENTINE",-95.67,3978.21
+2024-02-15,"DUPLICATE AMOUNT TEST",-45.67,3932.54
+2024-02-16,"PENDING TRANSACTION",-123.45,3809.09

package/test-exports/sample_bank_statement.csv

@@ -0,0 +1,7 @@
+Date,Amount,Description
+01/15/2025,25.50,Coffee Shop Purchase
+01/16/2025,-100.00,ATM Withdrawal
+01/17/2025,45.75,Grocery Store
+01/18/2025,15.99,Netflix Subscription
+01/19/2025,200.00,Paycheck Deposit
+01/20/2025,32.45,Gas Station

package/test-exports/ynab_account_e9ddc2a6_minimal_1items_2025-11-19_09-04-53.json

@@ -0,0 +1,23 @@
+{
+  "export_info": {
+    "exported_at": "2025-11-19T17:04:53.492Z",
+    "total_transactions": 1,
+    "minimal": true,
+    "filters": {
+      "budget_id": "7b47d8bb-ce4c-40c0-a9eb-c6d715af9a76",
+      "account_id": "e9ddc2a6-f4ae-4f95-b45a-831cf1d7b90c",
+      "category_id": null,
+      "since_date": null,
+      "type": null
+    }
+  },
+  "transactions": [
+    {
+      "id": "93e4355b-6c45-4f73-899d-53b2c4ef8c7d",
+      "date": "2025-11-17",
+      "amount": 10000000,
+      "payee_name": "Starting Balance",
+      "cleared": "cleared"
+    }
+  ]
+}

package/test-exports/ynab_account_e9ddc2a6_minimal_1items_2025-11-19_10-37-42.json

@@ -0,0 +1,23 @@
+{
+  "export_info": {
+    "exported_at": "2025-11-19T18:37:42.030Z",
+    "total_transactions": 1,
+    "minimal": true,
+    "filters": {
+      "budget_id": "7b47d8bb-ce4c-40c0-a9eb-c6d715af9a76",
+      "account_id": "e9ddc2a6-f4ae-4f95-b45a-831cf1d7b90c",
+      "category_id": null,
+      "since_date": null,
+      "type": null
+    }
+  },
+  "transactions": [
+    {
+      "id": "93e4355b-6c45-4f73-899d-53b2c4ef8c7d",
+      "date": "2025-11-17",
+      "amount": 10000000,
+      "payee_name": "Starting Balance",
+      "cleared": "cleared"
+    }
+  ]
+}

package/test-exports/ynab_account_e9ddc2a6_minimal_4items_2025-11-19_09-02-09.json

@@ -0,0 +1,44 @@
+{
+  "export_info": {
+    "exported_at": "2025-11-19T17:02:09.880Z",
+    "total_transactions": 4,
+    "minimal": true,
+    "filters": {
+      "budget_id": "7b47d8bb-ce4c-40c0-a9eb-c6d715af9a76",
+      "account_id": "e9ddc2a6-f4ae-4f95-b45a-831cf1d7b90c",
+      "category_id": null,
+      "since_date": null,
+      "type": null
+    }
+  },
+  "transactions": [
+    {
+      "id": "93e4355b-6c45-4f73-899d-53b2c4ef8c7d",
+      "date": "2025-11-17",
+      "amount": 10000000,
+      "payee_name": "Starting Balance",
+      "cleared": "cleared"
+    },
+    {
+      "id": "1aa8be76-7b33-471d-8a6c-dd3193b8c7e0",
+      "date": "2025-11-19",
+      "amount": -3000,
+      "payee_name": "Test Update Payee 1763571729127",
+      "cleared": "uncleared"
+    },
+    {
+      "id": "fce0d2e4-91aa-4d37-abcd-33dfb4e9d803",
+      "date": "2025-11-19",
+      "amount": -2000,
+      "payee_name": "Test Payee 2 1763571728468",
+      "cleared": "uncleared"
+    },
+    {
+      "id": "b26a77cc-6cc4-4e2d-8ffa-72fcd00a2cde",
+      "date": "2025-11-19",
+      "amount": -1000,
+      "payee_name": "Test Payee 1 1763571728468",
+      "cleared": "uncleared"
+    }
+  ]
+}

package/test-exports/ynab_account_e9ddc2a6_minimal_6items_2025-11-19_10-37-52.json

@@ -0,0 +1,58 @@
+{
+  "export_info": {
+    "exported_at": "2025-11-19T18:37:52.409Z",
+    "total_transactions": 6,
+    "minimal": true,
+    "filters": {
+      "budget_id": "7b47d8bb-ce4c-40c0-a9eb-c6d715af9a76",
+      "account_id": "e9ddc2a6-f4ae-4f95-b45a-831cf1d7b90c",
+      "category_id": null,
+      "since_date": null,
+      "type": null
+    }
+  },
+  "transactions": [
+    {
+      "id": "93e4355b-6c45-4f73-899d-53b2c4ef8c7d",
+      "date": "2025-11-17",
+      "amount": 10000000,
+      "payee_name": "Starting Balance",
+      "cleared": "cleared"
+    },
+    {
+      "id": "fa32d5e7-76c5-46f0-9daa-c96a06b0a16c",
+      "date": "2025-11-19",
+      "amount": -3000,
+      "payee_name": "Test Update Payee 1763577471655",
+      "cleared": "uncleared"
+    },
+    {
+      "id": "883f3e33-e8fd-48d7-bb1f-55803b7c310b",
+      "date": "2025-11-19",
+      "amount": -2500,
+      "payee_name": "Bulk Workflow Payee 2 1763577462035",
+      "cleared": "uncleared"
+    },
+    {
+      "id": "d0ef74ff-a0d3-4f81-ab00-355eee55d6f1",
+      "date": "2025-11-19",
+      "amount": -2000,
+      "payee_name": "Test Payee 2 1763577471385",
+      "cleared": "uncleared"
+    },
+    {
+      "id": "863445bc-f3a6-4d5a-a2bf-6f91e39c2ec7",
+      "date": "2025-11-19",
+      "amount": -1500,
+      "payee_name": "Bulk Workflow Payee 1 1763577462035",
+      "cleared": "uncleared"
+    },
+    {
+      "id": "d211482a-6082-471b-a318-6679a6c35bfd",
+      "date": "2025-11-19",
+      "amount": -1000,
+      "payee_name": "Test Payee 1 1763577471385",
+      "cleared": "uncleared"
+    }
+  ]
+}

package/test-exports/ynab_since_2025-11-01_account_4c18e9f0_minimal_14items_2025-11-16_10-07-10.json

@@ -0,0 +1,115 @@
+{
+  "export_info": {
+    "exported_at": "2025-11-16T18:07:10.599Z",
+    "total_transactions": 14,
+    "minimal": true,
+    "filters": {
+      "budget_id": "bf00f94f-f532-4b2c-a39c-e8d9a963effd",
+      "account_id": "4c18e9f0-8aa6-4427-98f5-55ce81d109cf",
+      "category_id": null,
+      "since_date": "2025-11-01",
+      "type": null,
+      "minimal": true
+    }
+  },
+  "transactions": [
+    {
+      "id": "382cbe8c-7715-48b0-b0a6-3ac0bc17f9c2_2025-11-01",
+      "date": "2025-11-01",
+      "amount": -210000,
+      "payee_name": "Transfer : N 🇼📈WS RESP",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "b6053873-f422-480f-beb0-0d271a36f719",
+      "date": "2025-11-01",
+      "amount": -136500,
+      "payee_name": "Costco Annual Renewal",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "47814a86-65f5-439a-8b1c-b5f50603de2c",
+      "date": "2025-11-02",
+      "amount": 637800,
+      "payee_name": "Mercury Speech",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "5b399d5a-578f-4234-8b4c-ad0921b66a93_2025-11-05",
+      "date": "2025-11-05",
+      "amount": -46800,
+      "payee_name": "Empire Life",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "84eff87c-0126-46f0-9bff-633604bcddec",
+      "date": "2025-11-06",
+      "amount": 2722020,
+      "payee_name": "Nurture Society for Learning and Development",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "769efb8e-dc6e-4a12-9852-eb470f639917",
+      "date": "2025-11-08",
+      "amount": 51620,
+      "payee_name": "Costco",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "a4172251-b266-4b83-bfd7-1433b20ffe06",
+      "date": "2025-11-08",
+      "amount": 67750,
+      "payee_name": "Costco",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "ef42495c-7e9e-4fb6-916f-074cc1671788",
+      "date": "2025-11-11",
+      "amount": 500000,
+      "payee_name": "Shelby Speech All Brains Clinic",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "5a7d4640-bfb1-46c6-a0c5-4884206deb65",
+      "date": "2025-11-14",
+      "amount": -2000000,
+      "payee_name": "Transfer : 📗✔️ K TD ALL-INCLUSIVE cheq",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "c9d36a31-f351-477a-9830-ed572fe00b9b",
+      "date": "2025-11-14",
+      "amount": -877860,
+      "payee_name": "Transfer : 🍊 💳  Tang MC",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "4c35aa51-9fc2-412f-b156-04476eb8160e",
+      "date": "2025-11-14",
+      "amount": -150000,
+      "payee_name": "Joy Schellenberg",
+      "cleared": "reconciled"
+    },
+    {
+      "id": "890f3612-380c-460d-be46-0e672e1102c0",
+      "date": "2025-11-14",
+      "amount": -70000,
+      "payee_name": "Monika Szatlowska",
+      "cleared": "cleared"
+    },
+    {
+      "id": "4aa92a3b-16ff-453d-8187-63e449f7147d",
+      "date": "2025-11-14",
+      "amount": 180000,
+      "payee_name": "Shelby Speech Private Pay",
+      "cleared": "cleared"
+    },
+    {
+      "id": "20baeae0-341b-49d1-8507-1cc9eaf2280b",
+      "date": "2025-11-14",
+      "amount": 2560870,
+      "payee_name": "PHSA",
+      "cleared": "reconciled"
+    }
+  ]
+}

package/test-reconcile-autodetect.js

@@ -0,0 +1,40 @@
+/**
+ * Test the auto-detect date range functionality
+ */
+
+import {
+  extractDateRangeFromCSV,
+  autoDetectCSVFormat,
+} from './dist/tools/compareTransactions/parser.js';
+
+const csvContent = `Date,Description,Debit,Credit,Balance
+11/10/2025,DOLLARAMA # 109,10.91,,
+10/15/2025,Uber Trip,30.50,,
+09/22/2025,CIRCLE K # 05844 A,18.84,,`;
+
+console.log('Testing auto-detection...');
+
+try {
+  // Test 1: Auto-detect format
+  console.log('\n1. Auto-detecting CSV format...');
+  const csvFormat = autoDetectCSVFormat(csvContent);
+  console.log('  ✓ Format detected:', JSON.stringify(csvFormat, null, 2));
+
+  // Test 2: Extract date range
+  console.log('\n2. Extracting date range...');
+  const { minDate, maxDate } = extractDateRangeFromCSV(csvContent, csvFormat);
+  console.log(`  ✓ Date range: ${minDate} to ${maxDate}`);
+
+  // Test 3: Calculate buffer date
+  console.log('\n3. Calculating YNAB fetch date with 7-day buffer...');
+  const minDateObj = new Date(minDate);
+  minDateObj.setDate(minDateObj.getDate() - 7);
+  const fetchDate = minDateObj.toISOString().split('T')[0];
+  console.log(`  ✓ YNAB fetch from: ${fetchDate}`);
+
+  console.log('\n✅ All tests passed!');
+} catch (error) {
+  console.error('\n❌ ERROR:', error.message);
+  console.error(error.stack);
+  process.exit(1);
+}