@dizzlkheinz/ynab-mcpb 0.18.3 → 0.18.4

package/dist/tools/transactionSchemas.js

@@ -0,0 +1,215 @@
+import { z } from 'zod/v4';
+export const ListTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().optional(),
+    category_id: z.string().optional(),
+    since_date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    type: z.enum(['uncategorized', 'unapproved']).optional(),
+})
+    .strict();
+export const GetTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transaction_id: z.string().min(1, 'Transaction ID is required'),
+})
+    .strict();
+export const CreateTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    amount: z.number().int('Amount must be an integer in milliunits'),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)'),
+    payee_name: z.string().optional(),
+    payee_id: z.string().optional(),
+    category_id: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    import_id: z.string().min(1, 'Import ID cannot be empty').optional(),
+    dry_run: z.boolean().optional(),
+    subtransactions: z
+        .array(z
+        .object({
+        amount: z.number().int('Subtransaction amount must be an integer in milliunits'),
+        payee_name: z.string().optional(),
+        payee_id: z.string().optional(),
+        category_id: z.string().optional(),
+        memo: z.string().optional(),
+    })
+        .strict())
+        .min(1, 'At least one subtransaction is required when provided')
+        .optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    if (data.subtransactions && data.subtransactions.length > 0) {
+        const total = data.subtransactions.reduce((sum, sub) => sum + sub.amount, 0);
+        if (total !== data.amount) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'Amount must equal the sum of subtransaction amounts',
+                path: ['amount'],
+            });
+        }
+    }
+});
+const BulkTransactionInputSchemaBase = CreateTransactionSchema.pick({
+    account_id: true,
+    amount: true,
+    date: true,
+    payee_name: true,
+    payee_id: true,
+    category_id: true,
+    memo: true,
+    cleared: true,
+    approved: true,
+    flag_color: true,
+    import_id: true,
+});
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
+export const CreateTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transactions: z
+        .array(BulkTransactionInputSchema)
+        .min(1, 'At least one transaction is required')
+        .max(100, 'A maximum of 100 transactions may be created at once'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+const ReceiptSplitItemSchema = z
+    .object({
+    name: z.string().min(1, 'Item name is required'),
+    amount: z.number().finite('Item amount must be a finite number'),
+    quantity: z
+        .number()
+        .finite('Quantity must be a finite number')
+        .positive('Quantity must be greater than zero')
+        .optional(),
+    memo: z.string().optional(),
+})
+    .strict();
+const ReceiptSplitCategorySchema = z
+    .object({
+    category_id: z.string().min(1, 'Category ID is required'),
+    category_name: z.string().optional(),
+    items: z.array(ReceiptSplitItemSchema).min(1, 'Each category must include at least one item'),
+})
+    .strict();
+export const CreateReceiptSplitTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    payee_name: z.string().min(1, 'Payee name is required'),
+    date: z
+        .string()
+        .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    memo: z.string().optional(),
+    receipt_subtotal: z
+        .number()
+        .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'),
+    receipt_total: z
+        .number()
+        .finite('Receipt total must be a finite number')
+        .refine((value) => value > 0, 'Receipt total must be greater than zero'),
+    categories: z
+        .array(ReceiptSplitCategorySchema)
+        .min(1, 'At least one categorized group is required to create a split transaction'),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    dry_run: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    const itemsSubtotal = data.categories
+        .flatMap((category) => category.items)
+        .reduce((sum, item) => sum + item.amount, 0);
+    if (data.receipt_subtotal !== undefined) {
+        const delta = Math.abs(data.receipt_subtotal - itemsSubtotal);
+        if (delta > 0.01) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Receipt subtotal (${data.receipt_subtotal.toFixed(2)}) does not match categorized items total (${itemsSubtotal.toFixed(2)})`,
+                path: ['receipt_subtotal'],
+            });
+        }
+    }
+    const expectedTotal = itemsSubtotal + data.receipt_tax;
+    const deltaTotal = Math.abs(expectedTotal - data.receipt_total);
+    if (deltaTotal > 0.01) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Receipt total (${data.receipt_total.toFixed(2)}) does not match subtotal plus tax (${expectedTotal.toFixed(2)})`,
+            path: ['receipt_total'],
+        });
+    }
+});
+export const UpdateTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transaction_id: z.string().min(1, 'Transaction ID is required'),
+    account_id: z.string().optional(),
+    amount: z.number().int('Amount must be an integer in milliunits').optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    payee_name: z.string().optional(),
+    payee_id: z.string().optional(),
+    category_id: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+const BulkUpdateTransactionInputSchema = z
+    .object({
+    id: z.string().min(1, 'Transaction ID is required'),
+    amount: z.number().int('Amount must be an integer in milliunits').optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    payee_name: z.string().optional(),
+    payee_id: z.string().optional(),
+    category_id: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    original_account_id: z.string().optional(),
+    original_date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+})
+    .strict();
+export const UpdateTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transactions: z
+        .array(BulkUpdateTransactionInputSchema)
+        .min(1, 'At least one transaction is required')
+        .max(100, 'A maximum of 100 transactions may be updated at once'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+export const DeleteTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transaction_id: z.string().min(1, 'Transaction ID is required'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();

package/dist/tools/transactionTools.d.ts

@@ -1,289 +1,10 @@
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import * as ynab from 'ynab';
-import type { SaveTransactionsResponseData } from 'ynab/dist/models/SaveTransactionsResponseData.js';
-import { z } from 'zod/v4';
 import type { ToolFactory } from '../types/toolRegistration.js';
 import type { DeltaFetcher } from './deltaFetcher.js';
 import type { DeltaCache } from '../server/deltaCache.js';
 import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
-export declare const ListTransactionsSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    account_id: z.ZodOptional<z.ZodString>;
-    category_id: z.ZodOptional<z.ZodString>;
-    since_date: z.ZodOptional<z.ZodString>;
-    type: z.ZodOptional<z.ZodEnum<{
-        uncategorized: "uncategorized";
-        unapproved: "unapproved";
-    }>>;
-}, z.core.$strict>;
-export type ListTransactionsParams = z.infer<typeof ListTransactionsSchema>;
-export declare const GetTransactionSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    transaction_id: z.ZodString;
-}, z.core.$strict>;
-export type GetTransactionParams = z.infer<typeof GetTransactionSchema>;
-export declare const CreateTransactionSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    account_id: z.ZodString;
-    amount: z.ZodNumber;
-    date: z.ZodString;
-    payee_name: z.ZodOptional<z.ZodString>;
-    payee_id: z.ZodOptional<z.ZodString>;
-    category_id: z.ZodOptional<z.ZodString>;
-    memo: z.ZodOptional<z.ZodString>;
-    cleared: z.ZodOptional<z.ZodEnum<{
-        cleared: "cleared";
-        uncleared: "uncleared";
-        reconciled: "reconciled";
-    }>>;
-    approved: z.ZodOptional<z.ZodBoolean>;
-    flag_color: z.ZodOptional<z.ZodEnum<{
-        red: "red";
-        orange: "orange";
-        yellow: "yellow";
-        green: "green";
-        blue: "blue";
-        purple: "purple";
-    }>>;
-    import_id: z.ZodOptional<z.ZodString>;
-    dry_run: z.ZodOptional<z.ZodBoolean>;
-    subtransactions: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        amount: z.ZodNumber;
-        payee_name: z.ZodOptional<z.ZodString>;
-        payee_id: z.ZodOptional<z.ZodString>;
-        category_id: z.ZodOptional<z.ZodString>;
-        memo: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-}, z.core.$strict>;
-export type CreateTransactionParams = z.infer<typeof CreateTransactionSchema>;
-type BulkTransactionInput = Omit<CreateTransactionParams, 'budget_id' | 'dry_run' | 'subtransactions'>;
-export declare const CreateTransactionsSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    transactions: z.ZodArray<z.ZodObject<{
-        date: z.ZodString;
-        cleared: z.ZodOptional<z.ZodEnum<{
-            cleared: "cleared";
-            uncleared: "uncleared";
-            reconciled: "reconciled";
-        }>>;
-        amount: z.ZodNumber;
-        memo: z.ZodOptional<z.ZodString>;
-        approved: z.ZodOptional<z.ZodBoolean>;
-        flag_color: z.ZodOptional<z.ZodEnum<{
-            red: "red";
-            orange: "orange";
-            yellow: "yellow";
-            green: "green";
-            blue: "blue";
-            purple: "purple";
-        }>>;
-        account_id: z.ZodString;
-        payee_id: z.ZodOptional<z.ZodString>;
-        category_id: z.ZodOptional<z.ZodString>;
-        import_id: z.ZodOptional<z.ZodString>;
-        payee_name: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    dry_run: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export type CreateTransactionsParams = z.infer<typeof CreateTransactionsSchema>;
-export interface BulkTransactionResult {
-    request_index: number;
-    status: 'created' | 'duplicate' | 'failed';
-    transaction_id?: string | undefined;
-    correlation_key: string;
-    error_code?: string | undefined;
-    error?: string | undefined;
-}
-export interface BulkCreateResponse {
-    success: boolean;
-    server_knowledge?: number;
-    summary: {
-        total_requested: number;
-        created: number;
-        duplicates: number;
-        failed: number;
-    };
-    results: BulkTransactionResult[];
-    transactions?: ynab.TransactionDetail[];
-    duplicate_import_ids?: string[];
-    message?: string;
-    mode?: 'full' | 'summary' | 'ids_only';
-}
-export declare function generateCorrelationKey(transaction: {
-    account_id?: string;
-    date?: string;
-    amount?: number;
-    payee_id?: string | null;
-    payee_name?: string | null;
-    category_id?: string | null;
-    memo?: string | null;
-    cleared?: ynab.TransactionClearedStatus;
-    approved?: boolean;
-    flag_color?: ynab.TransactionFlagColor | null;
-    import_id?: string | null;
-}): string;
-type CorrelationPayload = Parameters<typeof generateCorrelationKey>[0];
-interface CorrelationPayloadInput {
-    account_id?: string | undefined;
-    date?: string | undefined;
-    amount?: number | undefined;
-    payee_id?: string | null | undefined;
-    payee_name?: string | null | undefined;
-    category_id?: string | null | undefined;
-    memo?: string | null | undefined;
-    cleared?: ynab.TransactionClearedStatus | undefined;
-    approved?: boolean | undefined;
-    flag_color?: ynab.TransactionFlagColor | null | undefined;
-    import_id?: string | null | undefined;
-}
-export declare function toCorrelationPayload(transaction: CorrelationPayloadInput): CorrelationPayload;
-export declare function correlateResults(requests: BulkTransactionInput[], responseData: SaveTransactionsResponseData, duplicateImportIds: Set<string>): BulkTransactionResult[];
-export declare const CreateReceiptSplitTransactionSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    account_id: z.ZodString;
-    payee_name: z.ZodString;
-    date: z.ZodOptional<z.ZodString>;
-    memo: z.ZodOptional<z.ZodString>;
-    receipt_subtotal: z.ZodOptional<z.ZodNumber>;
-    receipt_tax: z.ZodNumber;
-    receipt_total: z.ZodNumber;
-    categories: z.ZodArray<z.ZodObject<{
-        category_id: z.ZodString;
-        category_name: z.ZodOptional<z.ZodString>;
-        items: z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            amount: z.ZodNumber;
-            quantity: z.ZodOptional<z.ZodNumber>;
-            memo: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-    cleared: z.ZodOptional<z.ZodEnum<{
-        cleared: "cleared";
-        uncleared: "uncleared";
-        reconciled: "reconciled";
-    }>>;
-    approved: z.ZodOptional<z.ZodBoolean>;
-    flag_color: z.ZodOptional<z.ZodEnum<{
-        red: "red";
-        orange: "orange";
-        yellow: "yellow";
-        green: "green";
-        blue: "blue";
-        purple: "purple";
-    }>>;
-    dry_run: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export type CreateReceiptSplitTransactionParams = z.infer<typeof CreateReceiptSplitTransactionSchema>;
-export declare const UpdateTransactionSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    transaction_id: z.ZodString;
-    account_id: z.ZodOptional<z.ZodString>;
-    amount: z.ZodOptional<z.ZodNumber>;
-    date: z.ZodOptional<z.ZodString>;
-    payee_name: z.ZodOptional<z.ZodString>;
-    payee_id: z.ZodOptional<z.ZodString>;
-    category_id: z.ZodOptional<z.ZodString>;
-    memo: z.ZodOptional<z.ZodString>;
-    cleared: z.ZodOptional<z.ZodEnum<{
-        cleared: "cleared";
-        uncleared: "uncleared";
-        reconciled: "reconciled";
-    }>>;
-    approved: z.ZodOptional<z.ZodBoolean>;
-    flag_color: z.ZodOptional<z.ZodEnum<{
-        red: "red";
-        orange: "orange";
-        yellow: "yellow";
-        green: "green";
-        blue: "blue";
-        purple: "purple";
-    }>>;
-    dry_run: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export type UpdateTransactionParams = z.infer<typeof UpdateTransactionSchema>;
-declare const BulkUpdateTransactionInputSchema: z.ZodObject<{
-    id: z.ZodString;
-    amount: z.ZodOptional<z.ZodNumber>;
-    date: z.ZodOptional<z.ZodString>;
-    payee_name: z.ZodOptional<z.ZodString>;
-    payee_id: z.ZodOptional<z.ZodString>;
-    category_id: z.ZodOptional<z.ZodString>;
-    memo: z.ZodOptional<z.ZodString>;
-    cleared: z.ZodOptional<z.ZodEnum<{
-        cleared: "cleared";
-        uncleared: "uncleared";
-        reconciled: "reconciled";
-    }>>;
-    approved: z.ZodOptional<z.ZodBoolean>;
-    flag_color: z.ZodOptional<z.ZodEnum<{
-        red: "red";
-        orange: "orange";
-        yellow: "yellow";
-        green: "green";
-        blue: "blue";
-        purple: "purple";
-    }>>;
-    original_account_id: z.ZodOptional<z.ZodString>;
-    original_date: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type BulkUpdateTransactionInput = z.infer<typeof BulkUpdateTransactionInputSchema>;
-export declare const UpdateTransactionsSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    transactions: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        amount: z.ZodOptional<z.ZodNumber>;
-        date: z.ZodOptional<z.ZodString>;
-        payee_name: z.ZodOptional<z.ZodString>;
-        payee_id: z.ZodOptional<z.ZodString>;
-        category_id: z.ZodOptional<z.ZodString>;
-        memo: z.ZodOptional<z.ZodString>;
-        cleared: z.ZodOptional<z.ZodEnum<{
-            cleared: "cleared";
-            uncleared: "uncleared";
-            reconciled: "reconciled";
-        }>>;
-        approved: z.ZodOptional<z.ZodBoolean>;
-        flag_color: z.ZodOptional<z.ZodEnum<{
-            red: "red";
-            orange: "orange";
-            yellow: "yellow";
-            green: "green";
-            blue: "blue";
-            purple: "purple";
-        }>>;
-        original_account_id: z.ZodOptional<z.ZodString>;
-        original_date: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    dry_run: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export type UpdateTransactionsParams = z.infer<typeof UpdateTransactionsSchema>;
-export interface BulkUpdateResult {
-    request_index: number;
-    status: 'updated' | 'failed';
-    transaction_id: string;
-    correlation_key: string;
-    error_code?: string;
-    error?: string;
-}
-export interface BulkUpdateResponse {
-    success: boolean;
-    server_knowledge?: number;
-    summary: {
-        total_requested: number;
-        updated: number;
-        failed: number;
-    };
-    results: BulkUpdateResult[];
-    transactions?: ynab.TransactionDetail[];
-    message?: string;
-    mode?: 'full' | 'summary' | 'ids_only';
-}
-export declare const DeleteTransactionSchema: z.ZodObject<{
-    budget_id: z.ZodString;
-    transaction_id: z.ZodString;
-    dry_run: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export type DeleteTransactionParams = z.infer<typeof DeleteTransactionSchema>;
+import { ListTransactionsParams, GetTransactionParams, CreateTransactionParams, CreateTransactionsParams, CreateReceiptSplitTransactionParams, UpdateTransactionParams, UpdateTransactionsParams, DeleteTransactionParams } from './transactionSchemas.js';
 export declare function handleListTransactions(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ListTransactionsParams): Promise<CallToolResult>;
 export declare function handleListTransactions(ynabAPI: ynab.API, params: ListTransactionsParams): Promise<CallToolResult>;
 export declare function handleGetTransaction(ynabAPI: ynab.API, params: GetTransactionParams): Promise<CallToolResult>;
@@ -300,4 +21,5 @@ export declare function handleCreateTransactions(ynabAPI: ynab.API, params: Crea
 export declare function handleUpdateTransactions(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: UpdateTransactionsParams): Promise<CallToolResult>;
 export declare function handleUpdateTransactions(ynabAPI: ynab.API, params: UpdateTransactionsParams): Promise<CallToolResult>;
 export declare const registerTransactionTools: ToolFactory;
-export {};
+export { ListTransactionsSchema, type ListTransactionsParams, GetTransactionSchema, type GetTransactionParams, CreateTransactionSchema, type CreateTransactionParams, CreateTransactionsSchema, type CreateTransactionsParams, CreateReceiptSplitTransactionSchema, type CreateReceiptSplitTransactionParams, UpdateTransactionSchema, type UpdateTransactionParams, UpdateTransactionsSchema, type UpdateTransactionsParams, type BulkUpdateTransactionInput, DeleteTransactionSchema, type DeleteTransactionParams, type BulkTransactionResult, type BulkCreateResponse, type BulkUpdateResult, type BulkUpdateResponse, type CorrelationPayload, type CorrelationPayloadInput, type CategorySource, type TransactionCacheInvalidationOptions, type ReceiptCategoryCalculation, type SubtransactionInput, type BulkTransactionInput, } from './transactionSchemas.js';
+export { generateCorrelationKey, toCorrelationPayload, correlateResults, estimatePayloadSize, finalizeResponse, finalizeBulkUpdateResponse, handleTransactionError, toMonthKey, ensureTransaction, appendCategoryIds, collectCategoryIdsFromSources, setsEqual, invalidateTransactionCaches, } from './transactionUtils.js';