@dizzlkheinz/ynab-mcpb 0.12.1 → 0.13.1

package/dist/tools/reconciliation/executor.js

@@ -139,10 +139,11 @@ export async function executeReconciliation(options) {
                     recordAlignmentIfNeeded(trigger);
                 }
                 catch (error) {
+                    const ynabError = normalizeYnabError(error);
                     if (bulkOperationDetails) {
                         bulkOperationDetails.transaction_failures += 1;
                     }
-                    const failureReason = error instanceof Error ? error.message : 'Unknown error occurred';
+                    const failureReason = ynabError.message || 'Unknown error occurred';
                     const failureAction = {
                         type: 'create_transaction_failed',
                         transaction: entry.saveTransaction,
@@ -155,6 +156,9 @@ export async function executeReconciliation(options) {
                         failureAction.bulk_chunk_index = options.chunkIndex;
                     }
                     actions_taken.push(failureAction);
+                    if (shouldPropagateYnabError(ynabError)) {
+                        throw attachStatusToError(ynabError);
+                    }
                 }
             }
             if (bulkOperationDetails && options.fallbackError && sequentialAttempts > 0) {
@@ -280,15 +284,21 @@ export async function executeReconciliation(options) {
                         bulkOperationDetails.bulk_successes += 1;
                     }
                     catch (error) {
-                        bulkOperationDetails.sequential_fallbacks += 1;
+                        const ynabError = normalizeYnabError(error);
+                        const failureReason = ynabError.message || 'unknown error';
                         bulkOperationDetails.bulk_chunk_failures += 1;
+                        if (shouldPropagateYnabError(ynabError)) {
+                            bulkOperationDetails.transaction_failures += chunk.length;
+                            throw attachStatusToError(ynabError);
+                        }
+                        bulkOperationDetails.sequential_fallbacks += 1;
                         actions_taken.push({
                             type: 'bulk_create_fallback',
                             transaction: null,
-                            reason: `Bulk chunk #${chunkIndex} failed (${error instanceof Error ? error.message : 'unknown error'}) - falling back to sequential creation`,
+                            reason: `Bulk chunk #${chunkIndex} failed (${failureReason}) - falling back to sequential creation`,
                             bulk_chunk_index: chunkIndex,
                         });
-                        await processSequentialEntries(chunk, { chunkIndex, fallbackError: error });
+                        await processSequentialEntries(chunk, { chunkIndex, fallbackError: ynabError });
                     }
                 }
             }
@@ -456,6 +466,77 @@ export async function executeReconciliation(options) {
     }
     return result;
 }
+const FATAL_YNAB_STATUS_CODES = new Set([400, 401, 403, 404, 429, 500]);
+function normalizeYnabError(error) {
+    const parseStatus = (value) => {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value === 'string') {
+            const numeric = Number(value);
+            if (Number.isFinite(numeric))
+                return numeric;
+        }
+        return undefined;
+    };
+    if (error instanceof Error) {
+        const status = parseStatus(error.status);
+        const detailSource = error.detail;
+        const detail = typeof detailSource === 'string' && detailSource.trim().length > 0 ? detailSource : undefined;
+        const result = {
+            name: error.name,
+            message: error.message || 'Unknown error occurred',
+        };
+        if (status !== undefined)
+            result.status = status;
+        if (detail !== undefined)
+            result.detail = detail;
+        return result;
+    }
+    if (error && typeof error === 'object') {
+        const errObj = error.error ?? error;
+        const status = parseStatus(errObj.id ?? errObj.status);
+        const detailCandidate = errObj.detail ??
+            errObj.message ??
+            errObj.name;
+        const detail = typeof detailCandidate === 'string' && detailCandidate.trim().length > 0
+            ? detailCandidate
+            : undefined;
+        const message = detail ??
+            (typeof errObj === 'string' && errObj.trim().length > 0 ? errObj : 'Unknown error occurred');
+        const name = typeof errObj.name === 'string'
+            ? errObj.name
+            : undefined;
+        const result = { message };
+        if (status !== undefined)
+            result.status = status;
+        if (name !== undefined)
+            result.name = name;
+        if (detail !== undefined)
+            result.detail = detail;
+        return result;
+    }
+    if (typeof error === 'string') {
+        return { message: error };
+    }
+    return { message: 'Unknown error occurred' };
+}
+function shouldPropagateYnabError(error) {
+    return error.status !== undefined && FATAL_YNAB_STATUS_CODES.has(error.status);
+}
+function attachStatusToError(error) {
+    const message = error.message || 'YNAB API error';
+    const err = new Error(message);
+    if (error.status !== undefined) {
+        err.status = error.status;
+    }
+    if (error.name) {
+        err.name = error.name;
+    }
+    if (error.detail && !message.includes(error.detail)) {
+        err.message = `${message} (${error.detail})`;
+    }
+    return err;
+}
 function formatDisplay(amount, currency) {
     return toMoneyValueFromDecimal(amount, currency).value_display;
 }

package/dist/tools/transactionTools.d.ts

@@ -58,13 +58,13 @@ 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.ZodPipe<z.ZodObject<{
+    transactions: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
         cleared: z.ZodOptional<z.ZodEnum<{
             cleared: "cleared";
             uncleared: "uncleared";
             reconciled: "reconciled";
         }>>;
-        date: z.ZodString;
         amount: z.ZodNumber;
         memo: z.ZodOptional<z.ZodString>;
         approved: z.ZodOptional<z.ZodBoolean>;
@@ -81,21 +81,7 @@ export declare const CreateTransactionsSchema: z.ZodObject<{
         category_id: z.ZodOptional<z.ZodString>;
         import_id: z.ZodOptional<z.ZodString>;
         payee_name: z.ZodOptional<z.ZodString>;
-        subtransactions: z.ZodOptional<z.ZodAny>;
-    }, z.core.$strict>, z.ZodTransform<BulkTransactionInput, {
-        date: string;
-        amount: number;
-        account_id: string;
-        cleared?: "cleared" | "uncleared" | "reconciled" | undefined;
-        memo?: string | undefined;
-        approved?: boolean | undefined;
-        flag_color?: "red" | "orange" | "yellow" | "green" | "blue" | "purple" | undefined;
-        payee_id?: string | undefined;
-        category_id?: string | undefined;
-        import_id?: string | undefined;
-        payee_name?: string | undefined;
-        subtransactions?: any;
-    }>>>;
+    }, z.core.$strict>>;
     dry_run: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type CreateTransactionsParams = z.infer<typeof CreateTransactionsSchema>;

package/dist/tools/transactionTools.js

@@ -161,23 +161,7 @@ const BulkTransactionInputSchemaBase = CreateTransactionSchema.pick({
     flag_color: true,
     import_id: true,
 });
-const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.extend({
-    subtransactions: z.any().optional(),
-})
-    .strict()
-    .superRefine((data, ctx) => {
-    if (data.subtransactions !== undefined) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'Subtransactions are not supported in bulk transaction creation',
-            path: ['subtransactions'],
-        });
-    }
-})
-    .transform((data) => {
-    const { subtransactions, ...rest } = data;
-    return rest;
-});
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
 export const CreateTransactionsSchema = z
     .object({
     budget_id: z.string().min(1, 'Budget ID is required'),
@@ -541,6 +525,10 @@ export async function handleListTransactions(ynabAPI, deltaFetcherOrParams, mayb
                             showing: `First ${preview.length} transactions:`,
                             total_count: transactions.length,
                             estimated_size_kb: Math.round(estimatedSize / 1024),
+                            cached: cacheHit,
+                            cache_info: cacheHit
+                                ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
+                                : 'Fresh data retrieved from YNAB API',
                             preview_transactions: preview.map((transaction) => ({
                                 id: transaction.id,
                                 date: transaction.date,

package/dist/utils/baseError.d.ts

@@ -0,0 +1,3 @@
+export declare class BaseError extends Error {
+    constructor(message: string);
+}

package/dist/utils/baseError.js

@@ -0,0 +1,7 @@
+export class BaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,13 @@
+export { BaseError } from './baseError.js';
+export { ValidationError } from './validationError.js';
+import { BaseError } from './baseError.js';
+export declare class ConfigurationError extends BaseError {
+}
+export declare class AuthenticationError extends BaseError {
+}
+export declare class YNABRequestError extends BaseError {
+    status: number;
+    statusText: string;
+    ynabErrorId?: string | undefined;
+    constructor(status: number, statusText: string, ynabErrorId?: string | undefined);
+}

package/dist/utils/errors.js

@@ -0,0 +1,15 @@
+export { BaseError } from './baseError.js';
+export { ValidationError } from './validationError.js';
+import { BaseError } from './baseError.js';
+export class ConfigurationError extends BaseError {
+}
+export class AuthenticationError extends BaseError {
+}
+export class YNABRequestError extends BaseError {
+    constructor(status, statusText, ynabErrorId) {
+        super(`YNAB API request failed: ${status} ${statusText}${ynabErrorId ? ` (Error ID: ${ynabErrorId})` : ''}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.ynabErrorId = ynabErrorId;
+    }
+}

package/dist/utils/validationError.d.ts

@@ -0,0 +1,3 @@
+import { BaseError } from './baseError.js';
+export declare class ValidationError extends BaseError {
+}

package/dist/utils/validationError.js

@@ -0,0 +1,3 @@
+import { BaseError } from './baseError.js';
+export class ValidationError extends BaseError {
+}

package/docs/plans/2025-11-20-reloadable-config-token-validation.md

@@ -0,0 +1,93 @@
+# Reloadable Config & Token Validation Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make config parsing reloadable for env-mutation tests/CI, harden token validation against malformed responses, and confirm integration runs with a valid YNAB token.
+
+**Architecture:** Parse env vars on-demand via `loadConfig()` (with a backward-compatible `config` singleton), inject per-server config instances instead of module globals, and wrap YNAB token validation failures (including non-JSON responses) into `AuthenticationError` with clear messaging.
+
+**Tech Stack:** Node + TypeScript, Zod, dotenv, Vitest, YNAB SDK, esbuild.
+
+### Task 1: Reloadable config loader
+
+**Files:**
+- Modify: `src/server/config.ts`
+- Modify: `src/server/__tests__/config.test.ts`
+
+**Step 1: Write failing test**  
+Add a test that calls `loadConfig()` twice after mutating `process.env.YNAB_ACCESS_TOKEN` (without re-importing the module) and expects the second call to return the updated token.
+
+**Step 2: Run test to verify failure**  
+Run `npx vitest run src/server/__tests__/config.test.ts` and confirm the new test fails because the loader is still tied to initial state.
+
+**Step 3: Implement reloadable loader**  
+Keep the Zod schema and explicit `config` singleton, but ensure `loadConfig()` re-parses `process.env` on every call (optionally allowing an env override for tests) and throws `ValidationError` on failure; keep `import 'dotenv/config'` so `.env` is loaded for Node execution.
+
+**Step 4: Re-run targeted test**  
+Re-run `npx vitest run src/server/__tests__/config.test.ts` to confirm the reloadable behavior passes.
+
+### Task 2: Inject per-instance config into YNABMCPServer
+
+**Files:**
+- Modify: `src/server/YNABMCPServer.ts`
+- Modify: `src/server/__tests__/YNABMCPServer.test.ts`
+- Modify: `src/server/__tests__/server-startup.integration.test.ts`
+
+**Step 1: Add/adjust tests**  
+Add coverage that changing `process.env.YNAB_ACCESS_TOKEN` before constructing a new `YNABMCPServer` produces a server wired to the new token (no module cache reset), and update expectations to align with `ValidationError` from `loadConfig()` where appropriate.
+
+**Step 2: Run tests to see failures**  
+Run `npx vitest run src/server/__tests__/YNABMCPServer.test.ts src/server/__tests__/server-startup.integration.test.ts`.
+
+**Step 3: Apply code changes**  
+Ensure the constructor stores `const configInstance = loadConfig()` and uses it for YNAB API creation, token validation, and tool execution auth; remove any lingering usage of the `config` singleton for runtime behavior.
+
+**Step 4: Re-run the affected tests**  
+Re-run the same Vitest targets to verify per-instance config wiring passes.
+
+### Task 3: Token validation resilience
+
+**Files:**
+- Modify: `src/server/YNABMCPServer.ts`
+- Modify: `src/server/__tests__/server-startup.integration.test.ts`
+
+**Step 1: Write failing test**  
+Mock `ynab.API().user.getUser` to reject with a `SyntaxError`/HTML-shaped error and expect `validateToken()` to reject with `AuthenticationError("Unexpected response from YNAB during token validation")` instead of surfacing the raw syntax failure.
+
+**Step 2: Run test to confirm failure**  
+Run `npx vitest run src/server/__tests__/server-startup.integration.test.ts`.
+
+**Step 3: Implement graceful handling**  
+Wrap token validation to catch non-JSON/SyntaxError cases (or responses lacking expected shape) and throw `AuthenticationError` with the clear message while preserving existing 401/403 mapping.
+
+**Step 4: Re-run validation tests**  
+Re-run the targeted integration test to ensure the new mapping passes.
+
+### Task 4: Test alignment & runner portability
+
+**Files:**
+- Modify: `src/server/__tests__/config.test.ts`
+- Modify: `scripts/run-throttled-integration-tests.js`
+
+**Step 1: Align config test patterns**  
+Update any assertions relying on module-level parsing side effects to use `vi.resetModules()` + `loadConfig()` explicitly for reload checks; keep singleton expectations where intentional.
+
+**Step 2: Harden integration runner on Windows**  
+Change the throttled runner to spawn Vitest via a platform-portable path (e.g., `node` + resolved `vitest` bin) to avoid `spawn EINVAL` with `.cmd` on Windows.
+
+**Step 3: Run quick smoke**  
+Run `node scripts/run-throttled-integration-tests.js --help` or kick a single file to ensure the wrapper executes without path errors.
+
+### Task 5: Full verification
+
+**Files/Commands:**
+- Commands: `npm test`, `npm run test:integration:core` (with `YNAB_ACCESS_TOKEN` set), optionally `npm run test:integration:domain`.
+
+**Step 1: Run unit suite**  
+Execute `npm test` to ensure unit coverage stays green.
+
+**Step 2: Run core integrations with real token**  
+Execute `npm run test:integration:core` using a known-good `YNAB_ACCESS_TOKEN`; capture any regressions.
+
+**Step 3: Optional extended coverage**  
+If time permits, run `npm run test:integration:domain` for broader confidence; note any skips or rate-limit impacts.