@dizzlkheinz/ynab-mcpb 0.26.2 → 0.26.4

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

@@ -4,335 +4,169 @@ import {
 	ReconcileAccountOutputSchema,
 } from "../reconciliationOutputs.js";
 
-/**
- * Test suite for discrepancy_direction validation refinement.
- *
- * The schema enforces that discrepancy_direction matches the numeric discrepancy.amount:
- * - If |amount| < 0.01: direction must be 'balanced'
- * - If amount >= 0.01: direction must be 'ynab_higher'
- * - If amount <= -0.01: direction must be 'bank_higher'
- */
-describe("ReconcileAccountOutputSchema - discrepancy_direction validation", () => {
-	const makeMoneyValue = (dollarAmount: number) => ({
-		value_milliunits: Math.round(dollarAmount * 1000),
-		value: dollarAmount,
-		value_display: `$${Math.abs(dollarAmount).toFixed(2)}`,
-		currency: "USD",
-		direction: (dollarAmount > 0
-			? "credit"
-			: dollarAmount < 0
-				? "debit"
-				: "balanced") as "credit" | "debit" | "balanced",
-	});
-
-	const createMinimalStructuredOutput = (
-		discrepancyAmount: number,
-		direction: "balanced" | "ynab_higher" | "bank_higher",
-	) => ({
-		human: "Reconciliation complete",
-		structured: {
-			version: "1.0.0",
-			schema_url: "https://example.com/schema",
-			generated_at: "2025-11-18T10:00:00Z",
-			account: {
-				id: "acct-123",
-				name: "Checking",
-			},
-			summary: {
-				statement_date_range: "2025-10-01 to 2025-10-31",
-				bank_transactions_count: 50,
-				ynab_transactions_count: 50,
-				auto_matched: 50,
-				suggested_matches: 0,
-				unmatched_bank: 0,
-				unmatched_ynab: 0,
-				current_cleared_balance: makeMoneyValue(1000),
-				target_statement_balance: makeMoneyValue(1000 + discrepancyAmount),
-				discrepancy: makeMoneyValue(discrepancyAmount),
-				discrepancy_explanation: "Test",
-			},
-			balance: {
-				current_cleared: makeMoneyValue(1000),
-				current_uncleared: makeMoneyValue(0),
-				current_total: makeMoneyValue(1000),
-				target_statement: makeMoneyValue(1000 + discrepancyAmount),
-				discrepancy: makeMoneyValue(discrepancyAmount),
-				on_track: Math.abs(discrepancyAmount) < 0.01,
-				discrepancy_direction: direction,
+describe("ReconcileAccountOutputSchema", () => {
+	it("accepts valid unmatched_only structured output", () => {
+		const output = {
+			human: "Reconciliation complete",
+			structured: {
+				unmatched_bank: [],
+				unmatched_ynab: [],
+				suggestions: [],
 			},
-			insights: [],
-			next_steps: [],
-			matches: {
-				auto: [],
-				suggested: [],
-			},
-			unmatched: {
-				bank: [],
-				ynab: [],
-			},
-		},
+		};
+		const result = ReconcileAccountOutputSchema.safeParse(output);
+		expect(result.success).toBe(true);
 	});
 
-	describe("balanced direction (|amount| < 0.01)", () => {
-		it('should accept direction "balanced" when amount is 0', () => {
-			const output = createMinimalStructuredOutput(0, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should accept direction "balanced" when amount is 0.001', () => {
-			const output = createMinimalStructuredOutput(0.001, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should accept direction "balanced" when amount is -0.009', () => {
-			const output = createMinimalStructuredOutput(-0.009, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should reject direction "ynab_higher" when amount is 0', () => {
-			const output = createMinimalStructuredOutput(0, "ynab_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual([
-					"balance",
-					"discrepancy_direction",
-				]);
-				expect(result.error.issues[0]?.message).toContain(
-					"Discrepancy direction mismatch",
-				);
-			}
-		});
-
-		it('should reject direction "bank_higher" when amount is 0.005', () => {
-			const output = createMinimalStructuredOutput(0.005, "bank_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual([
-					"balance",
-					"discrepancy_direction",
-				]);
-			}
-		});
+	it("rejects output without structured field", () => {
+		const output = { human: "Reconciliation complete" };
+		const result = ReconcileAccountOutputSchema.safeParse(output);
+		expect(result.success).toBe(false);
 	});
 
-	describe("ynab_higher direction (amount >= 0.01)", () => {
-		it('should accept direction "ynab_higher" when amount is 25.50', () => {
-			const output = createMinimalStructuredOutput(25.5, "ynab_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should accept direction "ynab_higher" when amount is 0.02 (just above threshold)', () => {
-			const output = createMinimalStructuredOutput(0.02, "ynab_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should reject direction "balanced" when amount is 100', () => {
-			const output = createMinimalStructuredOutput(100, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual([
-					"balance",
-					"discrepancy_direction",
-				]);
-				expect(result.error.issues[0]?.message).toContain(
-					"Discrepancy direction mismatch",
-				);
-			}
-		});
-
-		it('should reject direction "bank_higher" when amount is 50', () => {
-			const output = createMinimalStructuredOutput(50, "bank_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual([
-					"balance",
-					"discrepancy_direction",
-				]);
-			}
-		});
+	it("rejects output with unknown fields in structured", () => {
+		const output = {
+			human: "Reconciliation complete",
+			structured: {
+				unmatched_bank: [],
+				unmatched_ynab: [],
+				suggestions: [],
+				extra_field: "not allowed",
+			},
+		};
+		const result = ReconcileAccountOutputSchema.safeParse(output);
+		expect(result.success).toBe(false);
 	});
 
-	describe("bank_higher direction (amount <= -0.01)", () => {
-		it('should accept direction "bank_higher" when amount is -25.50', () => {
-			const output = createMinimalStructuredOutput(-25.5, "bank_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should accept direction "bank_higher" when amount is -0.02 (just below threshold)', () => {
-			const output = createMinimalStructuredOutput(-0.02, "bank_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should reject direction "balanced" when amount is -100', () => {
-			const output = createMinimalStructuredOutput(-100, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual([
-					"balance",
-					"discrepancy_direction",
-				]);
-				expect(result.error.issues[0]?.message).toContain(
-					"Discrepancy direction mismatch",
-				);
-			}
-		});
-
-		it('should reject direction "ynab_higher" when amount is -50', () => {
-			const output = createMinimalStructuredOutput(-50, "ynab_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual([
-					"balance",
-					"discrepancy_direction",
-				]);
-			}
-		});
+	it("accepts output with execution_summary", () => {
+		const output = {
+			human: "Reconciliation complete",
+			structured: {
+				unmatched_bank: [],
+				unmatched_ynab: [],
+				suggestions: [],
+				execution_summary: {
+					transactions_created: 5,
+					transactions_updated: 2,
+					dates_adjusted: 0,
+					dry_run: false,
+					balance_status: "balanced",
+					recommendations: ["Review matched transactions"],
+				},
+			},
+		};
+		const result = ReconcileAccountOutputSchema.safeParse(output);
+		expect(result.success).toBe(true);
 	});
 
-	describe("edge cases", () => {
-		it('should accept exactly 0.01 as requiring "ynab_higher"', () => {
-			const output = createMinimalStructuredOutput(0.01, "ynab_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should accept exactly -0.01 as requiring "bank_higher"', () => {
-			const output = createMinimalStructuredOutput(-0.01, "bank_higher");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
-
-		it('should reject "balanced" for exactly 0.01', () => {
-			const output = createMinimalStructuredOutput(0.01, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-		});
-
-		it('should reject "balanced" for exactly -0.01', () => {
-			const output = createMinimalStructuredOutput(-0.01, "balanced");
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(false);
-		});
+	it("accepts output without execution_summary", () => {
+		const output = {
+			human: "Reconciliation complete",
+			structured: {
+				unmatched_bank: [],
+				unmatched_ynab: [],
+				suggestions: [],
+			},
+		};
+		const result = ReconcileAccountOutputSchema.safeParse(output);
+		expect(result.success).toBe(true);
 	});
+});
 
-	describe("human-only output (no validation)", () => {
-		it("should accept human-only output without structured data", () => {
-			const output = {
-				human: "Reconciliation complete - everything balanced",
-			};
-			const result = ReconcileAccountOutputSchema.safeParse(output);
-			expect(result.success).toBe(true);
-		});
+describe("MoneyValueSchema - non-finite value validation", () => {
+	it("should reject NaN value", () => {
+		const invalid = {
+			value_milliunits: 0,
+			value: Number.NaN,
+			value_display: "$NaN",
+			currency: "USD",
+			direction: "balanced",
+		};
+		const result = MoneyValueSchema.safeParse(invalid);
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.error.issues[0]?.path).toEqual(["value"]);
+		}
 	});
 
-	describe("MoneyValueSchema - non-finite value validation", () => {
-		it("should reject NaN value", () => {
-			const invalid = {
-				value_milliunits: 0,
-				value: Number.NaN,
-				value_display: "$NaN",
-				currency: "USD",
-				direction: "balanced",
-			};
-			const result = MoneyValueSchema.safeParse(invalid);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual(["value"]);
-			}
-		});
-
-		it("should reject positive Infinity value", () => {
-			const invalid = {
-				value_milliunits: 0,
-				value: Number.POSITIVE_INFINITY,
-				value_display: "$Infinity",
-				currency: "USD",
-				direction: "credit",
-			};
-			const result = MoneyValueSchema.safeParse(invalid);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual(["value"]);
-			}
-		});
+	it("should reject positive Infinity value", () => {
+		const invalid = {
+			value_milliunits: 0,
+			value: Number.POSITIVE_INFINITY,
+			value_display: "$Infinity",
+			currency: "USD",
+			direction: "credit",
+		};
+		const result = MoneyValueSchema.safeParse(invalid);
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.error.issues[0]?.path).toEqual(["value"]);
+		}
+	});
 
-		it("should reject negative Infinity value", () => {
-			const invalid = {
-				value_milliunits: 0,
-				value: Number.NEGATIVE_INFINITY,
-				value_display: "-$Infinity",
-				currency: "USD",
-				direction: "debit",
-			};
-			const result = MoneyValueSchema.safeParse(invalid);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual(["value"]);
-			}
-		});
+	it("should reject negative Infinity value", () => {
+		const invalid = {
+			value_milliunits: 0,
+			value: Number.NEGATIVE_INFINITY,
+			value_display: "-$Infinity",
+			currency: "USD",
+			direction: "debit",
+		};
+		const result = MoneyValueSchema.safeParse(invalid);
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.error.issues[0]?.path).toEqual(["value"]);
+		}
+	});
 
-		it("should reject non-integer value_milliunits", () => {
-			const invalid = {
-				value_milliunits: 25.5,
-				value: 0.0255,
-				value_display: "$0.03",
-				currency: "USD",
-				direction: "credit",
-			};
-			const result = MoneyValueSchema.safeParse(invalid);
-			expect(result.success).toBe(false);
-			if (!result.success) {
-				expect(result.error.issues[0]?.path).toEqual(["value_milliunits"]);
-			}
-		});
+	it("should reject non-integer value_milliunits", () => {
+		const invalid = {
+			value_milliunits: 25.5,
+			value: 0.0255,
+			value_display: "$0.03",
+			currency: "USD",
+			direction: "credit",
+		};
+		const result = MoneyValueSchema.safeParse(invalid);
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.error.issues[0]?.path).toEqual(["value_milliunits"]);
+		}
+	});
 
-		it("should accept finite positive amounts", () => {
-			const valid = {
-				value_milliunits: 25500,
-				value: 25.5,
-				value_display: "$25.50",
-				currency: "USD",
-				direction: "credit",
-			};
-			const result = MoneyValueSchema.safeParse(valid);
-			expect(result.success).toBe(true);
-		});
+	it("should accept finite positive amounts", () => {
+		const valid = {
+			value_milliunits: 25500,
+			value: 25.5,
+			value_display: "$25.50",
+			currency: "USD",
+			direction: "credit",
+		};
+		const result = MoneyValueSchema.safeParse(valid);
+		expect(result.success).toBe(true);
+	});
 
-		it("should accept finite negative amounts", () => {
-			const valid = {
-				value_milliunits: -25500,
-				value: -25.5,
-				value_display: "-$25.50",
-				currency: "USD",
-				direction: "debit",
-			};
-			const result = MoneyValueSchema.safeParse(valid);
-			expect(result.success).toBe(true);
-		});
+	it("should accept finite negative amounts", () => {
+		const valid = {
+			value_milliunits: -25500,
+			value: -25.5,
+			value_display: "-$25.50",
+			currency: "USD",
+			direction: "debit",
+		};
+		const result = MoneyValueSchema.safeParse(valid);
+		expect(result.success).toBe(true);
+	});
 
-		it("should accept zero", () => {
-			const valid = {
-				value_milliunits: 0,
-				value: 0,
-				value_display: "$0.00",
-				currency: "USD",
-				direction: "balanced",
-			};
-			const result = MoneyValueSchema.safeParse(valid);
-			expect(result.success).toBe(true);
-		});
+	it("should accept zero", () => {
+		const valid = {
+			value_milliunits: 0,
+			value: 0,
+			value_display: "$0.00",
+			currency: "USD",
+			direction: "balanced",
+		};
+		const result = MoneyValueSchema.safeParse(valid);
+		expect(result.success).toBe(true);
 	});
 });

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

@@ -495,6 +495,36 @@ export const ExecutionActionRecordSchema = z.discriminatedUnion("type", [
 		reason: z.string(),
 		bulk_chunk_index: z.number(),
 	}),
+	// Bulk update chunk failure
+	z.object({
+		type: z.literal("batch_update_failed"),
+		transaction: z.null(),
+		reason: z.string(),
+	}),
+	// Bulk reconcile chunk failure
+	z.object({
+		type: z.literal("batch_reconcile_failed"),
+		transaction: z.null(),
+		reason: z.string(),
+	}),
+	// All matched transactions marked reconciled
+	z.object({
+		type: z.literal("reconciliation_complete"),
+		transaction: z.null(),
+		reason: z.string(),
+	}),
+	// Diagnostic: STEP 3 entry metadata
+	z.object({
+		type: z.literal("diagnostic_step3_entry"),
+		transaction: z.null(),
+		reason: z.string(),
+	}),
+	// Diagnostic: unmatched YNAB transaction details
+	z.object({
+		type: z.literal("diagnostic_unmatched_ynab"),
+		transaction: z.record(z.string(), z.unknown()),
+		reason: z.string(),
+	}),
 ]);
 
 export type ExecutionActionRecord = z.infer<typeof ExecutionActionRecordSchema>;
@@ -693,41 +723,25 @@ export const CsvFormatMetadataSchema = z.object({
 
 export type CsvFormatMetadata = z.infer<typeof CsvFormatMetadataSchema>;
 
-// Define the structured data schema without refinement first
-const StructuredReconciliationDataBaseSchema = z.object({
-	version: z.string(),
-	schema_url: z.string(),
-	generated_at: z.string(),
-	account: z.object({
-		id: z.string().optional(),
-		name: z.string().optional(),
-	}),
-	summary: ReconciliationSummarySchema,
-	balance: BalanceInfoSchema.extend({
-		discrepancy_direction: z.enum(["balanced", "ynab_higher", "bank_higher"]),
-	}),
-	insights: z.array(ReconciliationInsightSchema),
-	next_steps: z.array(z.string()),
-	matches: z.object({
-		auto: z.array(TransactionMatchSchema),
-		suggested: z.array(TransactionMatchSchema),
-	}),
-	unmatched: z.object({
-		bank: z.array(BankTransactionSchema),
-		ynab: z.array(YNABTransactionSimpleSchema),
-		ynab_outside_date_range: z.array(YNABTransactionSimpleSchema).optional(),
-	}),
-	recommendations: z.array(ActionableRecommendationSchema).optional(),
-	csv_format: CsvFormatMetadataSchema.optional(),
-	execution: ExecutionResultSchema.optional(),
-	audit: AuditMetadataSchema.optional(),
+export const ExecutionSummaryOutputSchema = z.object({
+	transactions_created: z.number().int(),
+	transactions_updated: z.number().int(),
+	dates_adjusted: z.number().int(),
+	dry_run: z.boolean(),
+	balance_status: z.enum(["balanced", "unbalanced", "not_verified"]).optional(),
+	recommendations: z.array(z.string()).optional(),
 });
 
+export type ExecutionSummaryOutput = z.infer<
+	typeof ExecutionSummaryOutputSchema
+>;
+
 export const StructuredReconciliationUnmatchedOnlySchema = z
 	.object({
 		unmatched_bank: z.array(BankTransactionSchema),
 		unmatched_ynab: z.array(YNABTransactionSimpleSchema),
 		suggestions: z.array(TransactionMatchSchema),
+		execution_summary: ExecutionSummaryOutputSchema.optional(),
 	})
 	.strict();
 
@@ -736,62 +750,11 @@ export type StructuredReconciliationUnmatchedOnly = z.infer<
 >;
 
 export const ReconcileAccountOutputSchema = z
-	.union([
-		// Human + structured data (when include_structured_data=true) - check this FIRST
-		z
-			.object({
-				human: z.string(),
-				structured: z.union([
-					StructuredReconciliationDataBaseSchema,
-					StructuredReconciliationUnmatchedOnlySchema,
-				]),
-			})
-			.strict(),
-		// Human narrative only (default mode) - check this SECOND
-		z
-			.object({
-				human: z.string(),
-			})
-			.strict(),
-	])
-	.refine(
-		(data) => {
-			// Only validate if this is the structured variant (has 'structured' property)
-			if (
-				"structured" in data &&
-				data.structured &&
-				"balance" in data.structured &&
-				typeof data.structured.balance === "object" &&
-				data.structured.balance !== null
-			) {
-				const discrepancyAmount = data.structured.balance.discrepancy.value;
-				const direction = data.structured.balance.discrepancy_direction;
-
-				// If absolute discrepancy < 0.01, direction must be 'balanced'
-				if (Math.abs(discrepancyAmount) < 0.01) {
-					return direction === "balanced";
-				}
-
-				// If discrepancy > 0, direction must be 'ynab_higher'
-				if (discrepancyAmount > 0) {
-					return direction === "ynab_higher";
-				}
-
-				// If discrepancy < 0, direction must be 'bank_higher'
-				if (discrepancyAmount < 0) {
-					return direction === "bank_higher";
-				}
-			}
-
-			// Human-only variant always passes validation
-			return true;
-		},
-		{
-			message:
-				"Discrepancy direction mismatch: direction must match the numeric discrepancy amount",
-			path: ["balance", "discrepancy_direction"],
-		},
-	);
+	.object({
+		human: z.string(),
+		structured: StructuredReconciliationUnmatchedOnlySchema,
+	})
+	.strict();
 
 export type ReconcileAccountOutput = z.infer<
 	typeof ReconcileAccountOutputSchema