@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/schemas/outputs/reconciliationOutputs.js

@@ -0,0 +1,377 @@
+import { z } from 'zod';
+export const MoneyValueSchema = z.object({
+    amount: z.number().finite(),
+    currency: z.string(),
+    formatted: z.string(),
+    memo: z.string().optional(),
+});
+export const IsoDateWithCalendarValidationSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+    .refine((dateStr) => {
+    const parsed = Date.parse(dateStr);
+    if (isNaN(parsed)) {
+        return false;
+    }
+    const date = new Date(parsed);
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    const reconstructed = `${year}-${month}-${day}`;
+    return reconstructed === dateStr;
+}, {
+    message: 'Invalid calendar date (e.g., month must be 01-12, day must be valid for the month)',
+});
+export const BankTransactionSchema = z.object({
+    id: z.string().uuid(),
+    date: IsoDateWithCalendarValidationSchema,
+    amount: z.number(),
+    payee: z.string(),
+    memo: z.string().optional(),
+    original_csv_row: z.number(),
+    amount_money: MoneyValueSchema,
+});
+export const YNABTransactionSimpleSchema = z.object({
+    id: z.string(),
+    date: IsoDateWithCalendarValidationSchema,
+    amount: z.number(),
+    payee_name: z.string().nullable(),
+    category_name: z.string().nullable(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']),
+    approved: z.boolean(),
+    memo: z.string().nullable().optional(),
+    amount_money: MoneyValueSchema,
+});
+export const MatchCandidateSchema = z.object({
+    ynab_transaction: YNABTransactionSimpleSchema,
+    confidence: z.number().min(0).max(100),
+    match_reason: z.string(),
+    explanation: z.string(),
+});
+export function deriveConfidenceFromScore(score) {
+    if (score >= 90)
+        return 'high';
+    if (score >= 60)
+        return 'medium';
+    if (score >= 1)
+        return 'low';
+    return 'none';
+}
+export const TransactionMatchSchema = z
+    .object({
+    bank_transaction: BankTransactionSchema,
+    ynab_transaction: YNABTransactionSimpleSchema.optional(),
+    candidates: z.array(MatchCandidateSchema).optional(),
+    confidence: z.enum(['high', 'medium', 'low', 'none']),
+    confidence_score: z.number().min(0).max(100),
+    match_reason: z.string(),
+    top_confidence: z.number().optional(),
+    action_hint: z.string().optional(),
+    recommendation: z.string().optional(),
+})
+    .refine((data) => {
+    const expectedConfidence = deriveConfidenceFromScore(data.confidence_score);
+    return data.confidence === expectedConfidence;
+}, {
+    message: 'Confidence mismatch: confidence enum does not match confidence_score',
+    path: ['confidence'],
+});
+export const BalanceInfoSchema = z.object({
+    current_cleared: MoneyValueSchema,
+    current_uncleared: MoneyValueSchema,
+    current_total: MoneyValueSchema,
+    target_statement: MoneyValueSchema,
+    discrepancy: MoneyValueSchema,
+    on_track: z.boolean(),
+});
+export const ReconciliationSummarySchema = z.object({
+    statement_date_range: z.string(),
+    bank_transactions_count: z.number(),
+    ynab_transactions_count: z.number(),
+    auto_matched: z.number(),
+    suggested_matches: z.number(),
+    unmatched_bank: z.number(),
+    unmatched_ynab: z.number(),
+    current_cleared_balance: MoneyValueSchema,
+    target_statement_balance: MoneyValueSchema,
+    discrepancy: MoneyValueSchema,
+    discrepancy_explanation: z.string(),
+});
+export const ReconciliationInsightSchema = z.object({
+    id: z.string(),
+    type: z.enum(['repeat_amount', 'near_match', 'anomaly']),
+    severity: z.enum(['info', 'warning', 'critical']),
+    title: z.string(),
+    description: z.string(),
+    evidence: z.record(z.string(), z.unknown()).optional(),
+});
+export const ActionableRecommendationSchema = z.discriminatedUnion('action_type', [
+    z.object({
+        id: z.string(),
+        action_type: z.literal('create_transaction'),
+        priority: z.enum(['high', 'medium', 'low']),
+        confidence: z.number().min(0).max(1),
+        message: z.string(),
+        reason: z.string(),
+        estimated_impact: MoneyValueSchema,
+        account_id: z.string(),
+        source_insight_id: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        parameters: z.object({
+            account_id: z.string(),
+            date: IsoDateWithCalendarValidationSchema,
+            amount: z.number(),
+            payee_name: z.string(),
+            memo: z.string().optional(),
+            cleared: z.enum(['cleared', 'uncleared']),
+            approved: z.boolean(),
+            category_id: z.string().optional(),
+        }),
+    }),
+    z.object({
+        id: z.string(),
+        action_type: z.literal('update_cleared'),
+        priority: z.enum(['high', 'medium', 'low']),
+        confidence: z.number().min(0).max(1),
+        message: z.string(),
+        reason: z.string(),
+        estimated_impact: MoneyValueSchema,
+        account_id: z.string(),
+        source_insight_id: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        parameters: z.object({
+            transaction_id: z.string(),
+            cleared: z.enum(['cleared', 'uncleared', 'reconciled']),
+        }),
+    }),
+    z.object({
+        id: z.string(),
+        action_type: z.literal('review_duplicate'),
+        priority: z.enum(['high', 'medium', 'low']),
+        confidence: z.number().min(0).max(1),
+        message: z.string(),
+        reason: z.string(),
+        estimated_impact: MoneyValueSchema,
+        account_id: z.string(),
+        source_insight_id: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        parameters: z.object({
+            candidate_ids: z.array(z.string()),
+            bank_transaction: BankTransactionSchema,
+            suggested_match_id: z.string().optional(),
+        }),
+    }),
+    z.object({
+        id: z.string(),
+        action_type: z.literal('manual_review'),
+        priority: z.enum(['high', 'medium', 'low']),
+        confidence: z.number().min(0).max(1),
+        message: z.string(),
+        reason: z.string(),
+        estimated_impact: MoneyValueSchema,
+        account_id: z.string(),
+        source_insight_id: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        parameters: z.object({
+            issue_type: z.string(),
+            related_transactions: z.array(z.string()),
+        }),
+    }),
+]);
+export const AccountSnapshotSchema = z.object({
+    balance: MoneyValueSchema,
+    cleared_balance: MoneyValueSchema,
+    uncleared_balance: MoneyValueSchema,
+});
+export const CreatedTransactionSchema = z
+    .object({
+    id: z.string(),
+    date: z.string(),
+    amount: z.number(),
+    memo: z.string().nullable().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    payee_name: z.string().nullable().optional(),
+    category_name: z.string().nullable().optional(),
+    import_id: z.string().nullable().optional(),
+})
+    .passthrough();
+export const TransactionCreationPayloadSchema = z.object({
+    account_id: z.string(),
+    date: z.string(),
+    amount: z.number(),
+    payee_name: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared']).optional(),
+    approved: z.boolean().optional(),
+    import_id: z.string().optional(),
+});
+export const TransactionUpdatePayloadSchema = z.object({
+    transaction_id: z.string(),
+    new_date: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+});
+export const DuplicateDetectionPayloadSchema = z.object({
+    transaction_id: z.string().nullable(),
+    import_id: z.string().optional(),
+});
+export const ExecutionActionRecordSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('create_transaction'),
+        transaction: CreatedTransactionSchema.nullable(),
+        reason: z.string(),
+        bulk_chunk_index: z.number().optional(),
+        correlation_key: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('create_transaction_failed'),
+        transaction: TransactionCreationPayloadSchema,
+        reason: z.string(),
+        bulk_chunk_index: z.number().optional(),
+        correlation_key: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('create_transaction_duplicate'),
+        transaction: DuplicateDetectionPayloadSchema,
+        reason: z.string(),
+        bulk_chunk_index: z.number(),
+        correlation_key: z.string().optional(),
+        duplicate: z.literal(true),
+    }),
+    z.object({
+        type: z.literal('update_transaction'),
+        transaction: z.union([
+            CreatedTransactionSchema.nullable(),
+            TransactionUpdatePayloadSchema,
+        ]),
+        reason: z.string(),
+    }),
+    z.object({
+        type: z.literal('balance_checkpoint'),
+        transaction: z.null(),
+        reason: z.string(),
+    }),
+    z.object({
+        type: z.literal('bulk_create_fallback'),
+        transaction: z.null(),
+        reason: z.string(),
+        bulk_chunk_index: z.number(),
+    }),
+]);
+export const ExecutionSummarySchema = z.object({
+    bank_transactions_count: z.number(),
+    ynab_transactions_count: z.number(),
+    matches_found: z.number(),
+    missing_in_ynab: z.number(),
+    missing_in_bank: z.number(),
+    transactions_created: z.number(),
+    transactions_updated: z.number(),
+    dates_adjusted: z.number(),
+    dry_run: z.boolean(),
+});
+export const BulkOperationDetailsSchema = z
+    .object({
+    chunks_processed: z.number(),
+    bulk_successes: z.number(),
+    sequential_fallbacks: z.number(),
+    duplicates_detected: z.number(),
+    failed_transactions: z.number(),
+    bulk_chunk_failures: z.number(),
+    transaction_failures: z.number(),
+    sequential_attempts: z.number().optional(),
+})
+    .refine((data) => data.failed_transactions === data.transaction_failures, {
+    message: 'failed_transactions must equal transaction_failures',
+});
+export const ExecutionResultSchema = z.object({
+    summary: ExecutionSummarySchema,
+    account_balance: z.object({
+        before: AccountSnapshotSchema,
+        after: AccountSnapshotSchema,
+    }),
+    actions_taken: z.array(ExecutionActionRecordSchema),
+    recommendations: z.array(z.string()),
+    balance_reconciliation: z.unknown().optional(),
+    bulk_operation_details: BulkOperationDetailsSchema.optional(),
+});
+export const AuditMetadataSchema = z
+    .object({
+    data_freshness: z.string(),
+    data_source: z.string(),
+    server_knowledge: z.number().optional(),
+    fetched_at: z.string(),
+    accounts_count: z.number().optional(),
+    transactions_count: z.number().optional(),
+    cache_status: z.object({
+        accounts_cached: z.boolean(),
+        transactions_cached: z.boolean(),
+        delta_merge_applied: z.boolean(),
+    }),
+})
+    .catchall(z.unknown());
+export const CsvFormatMetadataSchema = z.object({
+    delimiter: z.string(),
+    decimal_separator: z.string(),
+    thousands_separator: z.string().nullable(),
+    date_format: z.string(),
+    header_row: z.boolean(),
+    date_column: z.string().nullable(),
+    amount_column: z.string().nullable(),
+    payee_column: z.string().nullable(),
+});
+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),
+    }),
+    recommendations: z.array(ActionableRecommendationSchema).optional(),
+    csv_format: CsvFormatMetadataSchema.optional(),
+    execution: ExecutionResultSchema.optional(),
+    audit: AuditMetadataSchema.optional(),
+});
+export const ReconcileAccountOutputSchema = z
+    .union([
+    z.object({
+        human: z.string(),
+        structured: StructuredReconciliationDataBaseSchema,
+    }),
+    z.object({
+        human: z.string(),
+    }),
+])
+    .refine((data) => {
+    if ('structured' in data && data.structured) {
+        const discrepancyAmount = data.structured.balance.discrepancy.amount;
+        const direction = data.structured.balance.discrepancy_direction;
+        if (Math.abs(discrepancyAmount) < 0.01) {
+            return direction === 'balanced';
+        }
+        if (discrepancyAmount > 0) {
+            return direction === 'ynab_higher';
+        }
+        if (discrepancyAmount < 0) {
+            return direction === 'bank_higher';
+        }
+    }
+    return true;
+}, {
+    message: 'Discrepancy direction mismatch: direction must match the numeric discrepancy amount',
+    path: ['balance', 'discrepancy_direction'],
+});