@dizzlkheinz/ynab-mcpb 0.18.1 → 0.18.3

package/dist/tools/deltaSupport.js

@@ -166,6 +166,19 @@ export function resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams
         throw new Error('resolveDeltaWriteArgs: When providing only 1 argument, it must be a params object. ' +
             `Got: ${getTypeName(deltaCacheOrParams)}`);
     }
+    if (sharedDeltaContext) {
+        if (!sharedDeltaContext.knowledgeStore) {
+            sharedDeltaContext.knowledgeStore = new ServerKnowledgeStore();
+        }
+        if (!sharedDeltaContext.deltaCache) {
+            sharedDeltaContext.deltaCache = new DeltaCache(cacheManager, sharedDeltaContext.knowledgeStore);
+        }
+        return {
+            deltaCache: sharedDeltaContext.deltaCache,
+            knowledgeStore: sharedDeltaContext.knowledgeStore,
+            params: deltaCacheOrParams,
+        };
+    }
     const fallbackKnowledgeStore = new ServerKnowledgeStore();
     const fallbackDeltaCache = new DeltaCache(cacheManager, fallbackKnowledgeStore);
     return {

package/dist/tools/transactionTools.js

@@ -358,10 +358,7 @@ function finalizeResponse(response) {
 const ReceiptSplitItemSchema = z
     .object({
     name: z.string().min(1, 'Item name is required'),
-    amount: z
-        .number()
-        .finite('Item amount must be a finite number')
-        .refine((value) => value >= 0, 'Item amount must be zero or greater'),
+    amount: z.number().finite('Item amount must be a finite number'),
     quantity: z
         .number()
         .finite('Quantity must be a finite number')
@@ -392,10 +389,7 @@ export const CreateReceiptSplitTransactionSchema = z
         .finite('Receipt subtotal must be a finite number')
         .refine((value) => value >= 0, 'Receipt subtotal must be zero or greater')
         .optional(),
-    receipt_tax: z
-        .number()
-        .finite('Receipt tax must be a finite number')
-        .refine((value) => value >= 0, 'Receipt tax must be zero or greater'),
+    receipt_tax: z.number().finite('Receipt tax must be a finite number'),
     receipt_total: z
         .number()
         .finite('Receipt total must be a finite number')
@@ -755,36 +749,264 @@ export async function handleCreateTransaction(ynabAPI, deltaCacheOrParams, knowl
         return handleTransactionError(error, 'Failed to create transaction');
     }
 }
+const BIG_TICKET_THRESHOLD_MILLIUNITS = 50000;
+const COLLAPSE_THRESHOLD = 5;
+const MAX_ITEMS_PER_MEMO = 5;
+const MAX_MEMO_LENGTH = 150;
+function truncateToLength(str, maxLength) {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    const ellipsis = '...';
+    return str.substring(0, maxLength - ellipsis.length) + ellipsis;
+}
 function buildItemMemo(item) {
     const quantitySuffix = item.quantity ? ` (x${item.quantity})` : '';
+    let result;
     if (item.memo && item.memo.trim().length > 0) {
-        return `${item.name}${quantitySuffix} - ${item.memo}`;
+        result = `${item.name}${quantitySuffix} - ${item.memo}`;
+    }
+    else if (quantitySuffix) {
+        result = `${item.name}${quantitySuffix}`;
     }
-    if (quantitySuffix) {
-        return `${item.name}${quantitySuffix}`;
+    else {
+        result = item.name;
     }
-    return item.name;
+    return truncateToLength(result, MAX_MEMO_LENGTH);
 }
-function distributeTaxProportionally(subtotalMilliunits, totalTaxMilliunits, categories) {
-    if (totalTaxMilliunits === 0) {
-        for (const category of categories)
-            category.tax_milliunits = 0;
-        return;
+function applySmartCollapseLogic(categoryCalculations, taxMilliunits) {
+    const specialItems = [];
+    const remainingItemsByCategory = [];
+    for (const category of categoryCalculations) {
+        const categorySpecials = [];
+        const categoryRemaining = [];
+        for (const item of category.items) {
+            const isNegative = item.amount_milliunits < 0;
+            const unitPrice = item.quantity
+                ? item.amount_milliunits / item.quantity
+                : item.amount_milliunits;
+            const isBigTicket = unitPrice > BIG_TICKET_THRESHOLD_MILLIUNITS;
+            if (isNegative || isBigTicket) {
+                categorySpecials.push(item);
+            }
+            else {
+                categoryRemaining.push(item);
+            }
+        }
+        for (const item of categorySpecials) {
+            specialItems.push({
+                item,
+                category_id: category.category_id,
+                category_name: category.category_name,
+            });
+        }
+        if (categoryRemaining.length > 0) {
+            remainingItemsByCategory.push({
+                category_id: category.category_id,
+                category_name: category.category_name,
+                items: categoryRemaining,
+            });
+        }
+    }
+    const totalRemainingItems = remainingItemsByCategory.reduce((sum, cat) => sum + cat.items.length, 0);
+    const shouldCollapse = totalRemainingItems >= COLLAPSE_THRESHOLD;
+    const subtransactions = [];
+    for (const special of specialItems) {
+        const memo = buildItemMemo({
+            name: special.item.name,
+            quantity: special.item.quantity,
+            memo: special.item.memo,
+        });
+        const payload = {
+            amount: -special.item.amount_milliunits,
+            category_id: special.category_id,
+        };
+        if (memo)
+            payload.memo = memo;
+        subtransactions.push(payload);
     }
-    if (subtotalMilliunits <= 0) {
-        throw new Error('Receipt subtotal must be greater than zero to distribute tax');
+    if (shouldCollapse) {
+        for (const categoryGroup of remainingItemsByCategory) {
+            const collapsedSubtransactions = collapseItemsByCategory(categoryGroup);
+            subtransactions.push(...collapsedSubtransactions);
+        }
+    }
+    else {
+        for (const categoryGroup of remainingItemsByCategory) {
+            for (const item of categoryGroup.items) {
+                const memo = buildItemMemo({
+                    name: item.name,
+                    quantity: item.quantity,
+                    memo: item.memo,
+                });
+                const payload = {
+                    amount: -item.amount_milliunits,
+                    category_id: categoryGroup.category_id,
+                };
+                if (memo)
+                    payload.memo = memo;
+                subtransactions.push(payload);
+            }
+        }
     }
-    let allocated = 0;
-    categories.forEach((category, index) => {
-        if (index === categories.length - 1) {
-            category.tax_milliunits = totalTaxMilliunits - allocated;
+    const taxSubtransactions = allocateTax(categoryCalculations, taxMilliunits);
+    subtransactions.push(...taxSubtransactions);
+    return subtransactions;
+}
+function collapseItemsByCategory(categoryGroup) {
+    const subtransactions = [];
+    const items = categoryGroup.items;
+    let currentBatch = [];
+    let currentBatchTotal = 0;
+    for (const item of items) {
+        if (currentBatch.length >= MAX_ITEMS_PER_MEMO) {
+            const memo = buildCollapsedMemo(currentBatch);
+            subtransactions.push({
+                amount: -currentBatchTotal,
+                category_id: categoryGroup.category_id,
+                memo,
+            });
+            currentBatch = [];
+            currentBatchTotal = 0;
+        }
+        const testBatch = [...currentBatch, item];
+        const testMemo = buildCollapsedMemo(testBatch);
+        if (testMemo.length <= MAX_MEMO_LENGTH) {
+            currentBatch.push(item);
+            currentBatchTotal += item.amount_milliunits;
         }
         else {
-            const proportionalTax = Math.round((totalTaxMilliunits * category.subtotal_milliunits) / subtotalMilliunits);
-            category.tax_milliunits = proportionalTax;
-            allocated += proportionalTax;
+            if (currentBatch.length > 0) {
+                const memo = buildCollapsedMemo(currentBatch);
+                subtransactions.push({
+                    amount: -currentBatchTotal,
+                    category_id: categoryGroup.category_id,
+                    memo,
+                });
+                currentBatch = [item];
+                currentBatchTotal = item.amount_milliunits;
+            }
+            else {
+                currentBatch = [item];
+                currentBatchTotal = item.amount_milliunits;
+            }
         }
-    });
+    }
+    if (currentBatch.length > 0) {
+        const memo = buildCollapsedMemo(currentBatch);
+        subtransactions.push({
+            amount: -currentBatchTotal,
+            category_id: categoryGroup.category_id,
+            memo,
+        });
+    }
+    return subtransactions;
+}
+function truncateItemName(name, amountSuffix, maxLength) {
+    const ellipsis = '...';
+    const availableForName = maxLength - ellipsis.length - amountSuffix.length;
+    if (availableForName <= 0) {
+        return amountSuffix.substring(0, maxLength);
+    }
+    return name.substring(0, availableForName) + ellipsis + amountSuffix;
+}
+function buildCollapsedMemo(items) {
+    const parts = [];
+    let currentLength = 0;
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (!item)
+            continue;
+        const amount = milliunitsToAmount(item.amount_milliunits);
+        const amountSuffix = ` $${amount.toFixed(2)}`;
+        let itemStr = `${item.name}${amountSuffix}`;
+        const separator = i > 0 ? ', ' : '';
+        if (parts.length === 0 && itemStr.length > MAX_MEMO_LENGTH) {
+            itemStr = truncateItemName(item.name, amountSuffix, MAX_MEMO_LENGTH);
+        }
+        const testLength = currentLength + separator.length + itemStr.length;
+        if (parts.length > 0 && testLength + 4 > MAX_MEMO_LENGTH) {
+            break;
+        }
+        parts.push(itemStr);
+        currentLength = testLength;
+    }
+    let result = parts.join(', ');
+    if (parts.length < items.length) {
+        result += '...';
+    }
+    return result;
+}
+function allocateTax(categoryCalculations, taxMilliunits) {
+    const subtransactions = [];
+    if (taxMilliunits === 0) {
+        return subtransactions;
+    }
+    if (taxMilliunits < 0) {
+        let largestReturnCategory = undefined;
+        let largestReturnAmount = 0;
+        for (const category of categoryCalculations) {
+            const categoryReturnAmount = category.items
+                .filter((item) => item.amount_milliunits < 0)
+                .reduce((sum, item) => sum + Math.abs(item.amount_milliunits), 0);
+            if (categoryReturnAmount > largestReturnAmount) {
+                largestReturnAmount = categoryReturnAmount;
+                largestReturnCategory = category;
+            }
+        }
+        if (!largestReturnCategory) {
+            largestReturnCategory = categoryCalculations[0];
+        }
+        if (largestReturnCategory) {
+            subtransactions.push({
+                amount: -taxMilliunits,
+                category_id: largestReturnCategory.category_id,
+                memo: 'Tax refund',
+            });
+        }
+        return subtransactions;
+    }
+    const positiveCategorySubtotals = categoryCalculations
+        .map((cat) => ({
+        category: cat,
+        positiveSubtotal: cat.items
+            .filter((item) => item.amount_milliunits > 0)
+            .reduce((sum, item) => sum + item.amount_milliunits, 0),
+    }))
+        .filter((x) => x.positiveSubtotal > 0);
+    if (positiveCategorySubtotals.length === 0) {
+        return subtransactions;
+    }
+    const totalPositiveSubtotal = positiveCategorySubtotals.reduce((sum, x) => sum + x.positiveSubtotal, 0);
+    let allocatedTax = 0;
+    const taxAllocations = [];
+    for (let i = 0; i < positiveCategorySubtotals.length; i++) {
+        const entry = positiveCategorySubtotals[i];
+        if (!entry)
+            continue;
+        const { category, positiveSubtotal } = entry;
+        if (i === positiveCategorySubtotals.length - 1) {
+            const taxAmount = taxMilliunits - allocatedTax;
+            if (taxAmount > 0) {
+                taxAllocations.push({ category, taxAmount });
+            }
+        }
+        else {
+            const taxAmount = Math.round((taxMilliunits * positiveSubtotal) / totalPositiveSubtotal);
+            if (taxAmount > 0) {
+                taxAllocations.push({ category, taxAmount });
+                allocatedTax += taxAmount;
+            }
+        }
+    }
+    for (const { category, taxAmount } of taxAllocations) {
+        subtransactions.push({
+            amount: -taxAmount,
+            category_id: category.category_id,
+            memo: `Tax - ${category.category_name ?? 'Uncategorized'}`,
+        });
+    }
+    return subtransactions;
 }
 export async function handleCreateReceiptSplitTransaction(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
     const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
@@ -817,29 +1039,24 @@ export async function handleCreateReceiptSplitTransaction(ynabAPI, deltaCacheOrP
     if (Math.abs(computedTotal - totalMilliunits) > 1) {
         throw new Error(`Receipt total (${milliunitsToAmount(totalMilliunits)}) does not equal subtotal plus tax (${milliunitsToAmount(computedTotal)})`);
     }
-    distributeTaxProportionally(subtotalMilliunits, taxMilliunits, categoryCalculations);
-    const subtransactions = categoryCalculations.flatMap((category) => {
-        const itemSubtransactions = category.items.map((item) => {
-            const memo = buildItemMemo({ name: item.name, quantity: item.quantity, memo: item.memo });
-            const payload = {
-                amount: -item.amount_milliunits,
-                category_id: category.category_id,
-            };
-            if (memo)
-                payload.memo = memo;
-            return payload;
-        });
-        const taxSubtransaction = category.tax_milliunits > 0
-            ? [
-                {
-                    amount: -category.tax_milliunits,
-                    category_id: category.category_id,
-                    memo: `Tax - ${category.category_name ?? 'Uncategorized'}`,
-                },
-            ]
-            : [];
-        return [...itemSubtransactions, ...taxSubtransaction];
-    });
+    const subtransactions = applySmartCollapseLogic(categoryCalculations, taxMilliunits);
+    if (taxMilliunits > 0) {
+        const positiveSubtotal = categoryCalculations.reduce((sum, cat) => sum + Math.max(0, cat.subtotal_milliunits), 0);
+        if (positiveSubtotal > 0) {
+            let remainingTax = taxMilliunits;
+            const positiveCats = categoryCalculations.filter((cat) => cat.subtotal_milliunits > 0);
+            positiveCats.forEach((cat, index) => {
+                if (index === positiveCats.length - 1) {
+                    cat.tax_milliunits = remainingTax;
+                }
+                else {
+                    const share = Math.round((cat.subtotal_milliunits / positiveSubtotal) * taxMilliunits);
+                    cat.tax_milliunits = share;
+                    remainingTax -= share;
+                }
+            });
+        }
+    }
     const receiptSummary = {
         subtotal: milliunitsToAmount(subtotalMilliunits),
         tax: milliunitsToAmount(taxMilliunits),

package/docs/technical/receipt-itemization-spec.md

@@ -0,0 +1,181 @@
+# Receipt Itemization Specification
+
+## Overview
+
+The `create_receipt_split_transaction` tool creates split transactions from receipts with proportional tax allocation. This spec defines the "smart collapse" behavior that reduces clutter for large receipts while preserving visibility for important items.
+
+## Collapsing Rules
+
+Items are processed in this order:
+
+### 1. Extract Special Items (Always Get Own Subtransaction)
+
+These items are never collapsed into a group:
+
+| Type | Condition | Example |
+|------|-----------|---------|
+| **Big ticket** | Unit price > $50 | TV $500 |
+| **Returns** | Negative amount | RETURN: Broken headphones -$29.99 |
+| **Discounts** | Negative amount | Member discount -$5.00 |
+
+**Clarifications:**
+
+- **Unit price, not line total**: If a receipt shows "2x Widget @ $30 = $60", each widget is $30 (not big ticket). Only items with unit price > $50 qualify.
+- **Returns and discounts** are both negative amounts. The AI calling this tool should provide appropriate memo text to distinguish them. Both always get their own subtransaction.
+
+### 2. Apply Threshold to Remaining Items
+
+After extracting special items, count the remaining positive items:
+
+- **Fewer than 5 remaining items**: Itemize each individually (one subtransaction per item)
+- **5 or more remaining items**: Collapse by category (see below)
+
+### 3. Collapse by Category
+
+When collapsing:
+
+- Group items by category
+- Maximum **5 items per subtransaction** memo
+- If a category has more than 5 items, create multiple subtransactions for that category
+- Memo format: `"Item1 $X.XX, Item2 $Y.YY, Item3 $Z.ZZ"`
+- **Memo length limit**: 150 characters max. If exceeded, truncate item list and append "..."
+- **Consistency rule**: If ANY category gets collapsed, ALL categories get collapsed. No mixed mode.
+
+### 4. Tax Handling
+
+**Allocation:**
+- Tax is allocated **proportionally** across categories based on positive subtotals only
+- Returns and discounts do NOT reduce the taxable base for other items
+- Returns and discounts receive NO tax allocation
+
+**Subtransactions:**
+- Each category with a positive subtotal gets its own **separate tax subtransaction**
+- Memo format: `"Tax - CategoryName"`
+- Categories with zero or negative subtotal after discounts: **no tax subtransaction**
+
+**Edge cases:**
+- **Tax = 0**: Skip all tax subtransactions
+- **Tax < 0** (refund scenario): Create a single `"Tax refund"` subtransaction with the negative amount, allocated to the category with the largest return
+
+### 5. Output Ordering
+
+Subtransactions are ordered as follows:
+
+1. Special items (returns, discounts, big tickets) - in receipt order
+2. Collapsed/itemized category groups - categories in input order
+3. Tax subtransactions - in category order
+
+## Validation Rules
+
+- **Every item must have a category**. Uncategorized items cause validation failure.
+- **Tax-exempt items**: Not supported in this version. All positive items are assumed taxable.
+
+## Configuration
+
+| Parameter | Value | Notes |
+|-----------|-------|-------|
+| Big ticket threshold | $50.00 | Unit price, not line total |
+| Collapse threshold | 5 items | Total remaining positive items after extracting specials |
+| Max items per memo | 5 | Creates additional subtransactions if exceeded |
+| Max memo length | 150 chars | Truncates with "..." if exceeded |
+
+## Examples
+
+### Example 1: Small Receipt (fewer than 5 items)
+
+Input: 3 grocery items
+
+Output:
+```
+$4.99  -> Groceries | memo: "Milk"
+$3.49  -> Groceries | memo: "Bread"
+$5.99  -> Groceries | memo: "Eggs"
+$1.16  -> Groceries | memo: "Tax - Groceries"
+```
+
+### Example 2: Large Single-Category Receipt
+
+Input: 12 grocery items
+
+Output:
+```
+$24.45 -> Groceries | memo: "Milk $4.99, Bread $3.49, Eggs $5.99, Cheese $10.99, Butter $2.99"
+$19.46 -> Groceries | memo: "Yogurt $6.47, Apples $4.00, Bananas $2.01, OJ $3.00, Cereal $3.98"
+$8.02  -> Groceries | memo: "Rice $5.00, Pasta $3.02"
+$4.15  -> Groceries | memo: "Tax - Groceries"
+```
+
+### Example 3: Mixed Receipt with Big Ticket Item
+
+Input: TV ($500), 8 grocery items
+
+Output:
+```
+$500.00 -> Electronics | memo: "TV"
+$24.45  -> Groceries   | memo: "Milk $4.99, Bread $3.49, Eggs $5.99, Cheese $10.99, Butter $2.99"
+$15.48  -> Groceries   | memo: "Yogurt $6.47, Apples $4.00, Bananas $2.01, OJ $3.00"
+$40.00  -> Electronics | memo: "Tax - Electronics"
+$3.19   -> Groceries   | memo: "Tax - Groceries"
+```
+
+### Example 4: Receipt with Return
+
+Input: 6 grocery items plus a return
+
+Output:
+```
+-$29.99 -> Electronics | memo: "RETURN: Broken headphones"
+$24.45  -> Groceries   | memo: "Milk $4.99, Bread $3.49, Eggs $5.99, Cheese $10.99, Butter $2.99"
+$10.48  -> Groceries   | memo: "Yogurt $6.47, Apples $4.01"
+$2.79   -> Groceries   | memo: "Tax - Groceries"
+```
+
+Note: The return receives no tax allocation. Tax is only applied to positive grocery items.
+
+### Example 5: Receipt with Discount
+
+Input: 6 grocery items with member discount
+
+Output:
+```
+-$5.00  -> Groceries | memo: "Member discount"
+$24.45  -> Groceries | memo: "Milk $4.99, Bread $3.49, Eggs $5.99, Cheese $10.99, Butter $2.99"
+$15.48  -> Groceries | memo: "Yogurt $6.47, Apples $4.00, Bananas $2.01, OJ $3.00"
+$3.19   -> Groceries | memo: "Tax - Groceries"
+```
+
+Note: The discount is a separate line item. Tax is calculated on the positive items only.
+
+### Example 6: Quantity Items (Not Big Ticket)
+
+Input: 3x Widgets @ $30 each ($90 line), plus 4 other items
+
+Total items: 7 (3 widgets + 4 others) -> collapse mode
+
+Output:
+```
+$90.00  -> Electronics | memo: "Widget $30.00, Widget $30.00, Widget $30.00"
+$45.00  -> Groceries   | memo: "Milk $10.00, Bread $10.00, Eggs $10.00, Cheese $15.00"
+$10.80  -> Electronics | memo: "Tax - Electronics"
+$3.60   -> Groceries   | memo: "Tax - Groceries"
+```
+
+Note: Each widget is $30 (under $50 threshold), so they collapse normally.
+
+### Example 7: Tax Refund Scenario
+
+Input: Return of $100 item, receipt shows -$8.00 tax
+
+Output:
+```
+-$100.00 -> Electronics | memo: "RETURN: Defective laptop"
+-$8.00   -> Electronics | memo: "Tax refund"
+```
+
+## Implementation Notes
+
+1. **Rounding**: Use largest-remainder method when distributing tax to avoid penny discrepancies
+2. **Order of operations**: Extract specials -> count remaining -> decide collapse -> distribute tax
+3. **Consistency**: If ANY category gets collapsed, ALL categories get collapsed (except specials)
+4. **Negative detection**: Any item with amount < 0 is treated as return/discount (gets own subtransaction)
+5. **Unit price extraction**: When items have quantity > 1, divide total by quantity to get unit price for $50 threshold check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dizzlkheinz/ynab-mcpb",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Model Context Protocol server for YNAB (You Need A Budget) integration",
   "main": "dist/index.js",
   "type": "module",

package/src/tools/__tests__/transactionTools.integration.test.ts

@@ -215,6 +215,10 @@ describeIntegration('Transaction Tools Integration', () => {
       const result = await handleCreateTransactions(ynabAPI, params);
       const response = parseToolResult(result);
 
+      if (response.error) {
+        console.error('Bulk Create Failed:', JSON.stringify(response.error, null, 2));
+      }
+
       if (trackCreatedIds && Array.isArray(response.results)) {
         const createdIds = response.results
           .filter(
@@ -281,7 +285,7 @@ describeIntegration('Transaction Tools Integration', () => {
       'should detect duplicates when reusing import IDs',
       { meta: { tier: 'domain', domain: 'transactions' } },
       async () => {
-        const importId = `MCP:DUP:${randomUUID()}`;
+        const importId = `MCP:DUP:${randomUUID().slice(0, 20)}`;
         await executeBulkCreate({
           budget_id: testBudgetId,
           transactions: [
@@ -302,6 +306,10 @@ describeIntegration('Transaction Tools Integration', () => {
           ],
         });
 
+        if (!response.summary) {
+          console.error('Duplicate test response:', JSON.stringify(response, null, 2));
+        }
+
         expect(response.summary.duplicates).toBe(1);
         expect(response.results[0].status).toBe('duplicate');
       },
@@ -797,6 +805,8 @@ describeIntegration('Transaction Tools Integration', () => {
             {
               id: 'invalid-transaction-id-12345',
               memo: 'This should fail',
+              original_account_id: testAccountId,
+              original_date: new Date().toISOString().slice(0, 10),
             },
           ],
         });