@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/deltaFetcher.ts

@@ -0,0 +1,278 @@
+import * as ynab from 'ynab';
+import { DeltaCache, type DeltaFetchResult } from '../server/deltaCache.js';
+import {
+  mergeFlatEntities,
+  mergeCategories,
+  mergeTransactions,
+  mergeMonths,
+} from '../server/deltaCache.merge.js';
+import { CacheManager, CACHE_TTLS } from '../server/cacheManager.js';
+
+export interface DeltaFetchOptions {
+  forceFullRefresh?: boolean;
+  ttl?: number;
+}
+
+export class DeltaFetcher {
+  constructor(
+    private readonly ynabAPI: ynab.API,
+    private readonly deltaCache: DeltaCache,
+  ) {}
+
+  async fetchAccounts(
+    budgetId: string,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.Account>> {
+    const cacheKey = CacheManager.generateKey('accounts', 'list', budgetId);
+    return await this.deltaCache.fetchWithDelta<ynab.Account>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response =
+          lastKnowledge !== undefined
+            ? await this.ynabAPI.accounts.getAccounts(budgetId, lastKnowledge)
+            : await this.ynabAPI.accounts.getAccounts(budgetId);
+        return {
+          data: response.data.accounts,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeFlatEntities,
+      this.buildDeltaOptions(CACHE_TTLS.ACCOUNTS, options),
+    );
+  }
+
+  async fetchCategories(
+    budgetId: string,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.CategoryGroupWithCategories>> {
+    const cacheKey = CacheManager.generateKey('categories', 'list', budgetId);
+    return await this.deltaCache.fetchWithDelta<ynab.CategoryGroupWithCategories>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response =
+          lastKnowledge !== undefined
+            ? await this.ynabAPI.categories.getCategories(budgetId, lastKnowledge)
+            : await this.ynabAPI.categories.getCategories(budgetId);
+        return {
+          data: response.data.category_groups,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeCategories,
+      this.buildDeltaOptions(CACHE_TTLS.CATEGORIES, options),
+    );
+  }
+
+  async fetchTransactions(
+    budgetId: string,
+    sinceDate?: string,
+    type?: ynab.GetTransactionsTypeEnum,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.TransactionDetail>> {
+    const normalizedSince = sinceDate ?? 'all';
+    const normalizedType = type ?? 'all';
+    const cacheKey = CacheManager.generateKey(
+      'transactions',
+      'list',
+      budgetId,
+      normalizedSince,
+      normalizedType,
+    );
+    return await this.deltaCache.fetchWithDelta<ynab.TransactionDetail>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response = await this.ynabAPI.transactions.getTransactions(
+          budgetId,
+          sinceDate,
+          type,
+          lastKnowledge,
+        );
+        return {
+          data: response.data.transactions,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeTransactions,
+      this.buildDeltaOptions(CACHE_TTLS.TRANSACTIONS, options),
+    );
+  }
+
+  async fetchTransactionsByAccount(
+    budgetId: string,
+    accountId: string,
+    sinceDate?: string,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.TransactionDetail>> {
+    const normalizedSince = sinceDate ?? 'all';
+    const cacheKey = CacheManager.generateKey(
+      'transactions',
+      'account',
+      budgetId,
+      accountId,
+      normalizedSince,
+    );
+    return await this.deltaCache.fetchWithDelta<ynab.TransactionDetail>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response = await this.ynabAPI.transactions.getTransactionsByAccount(
+          budgetId,
+          accountId,
+          sinceDate,
+          undefined,
+          lastKnowledge,
+        );
+        return {
+          data: response.data.transactions,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeTransactions,
+      this.buildDeltaOptions(CACHE_TTLS.TRANSACTIONS, options),
+    );
+  }
+
+  async fetchAccountsFull(budgetId: string): Promise<DeltaFetchResult<ynab.Account>> {
+    const response = await this.ynabAPI.accounts.getAccounts(budgetId);
+    const accounts = response.data.accounts.filter((account) => !account.deleted);
+    return {
+      data: accounts,
+      wasCached: false,
+      usedDelta: false,
+      serverKnowledge: response.data.server_knowledge ?? 0,
+    };
+  }
+
+  async fetchTransactionsByAccountFull(
+    budgetId: string,
+    accountId: string,
+    sinceDate?: string,
+  ): Promise<DeltaFetchResult<ynab.TransactionDetail>> {
+    const response = await this.ynabAPI.transactions.getTransactionsByAccount(
+      budgetId,
+      accountId,
+      sinceDate,
+    );
+    const transactions = response.data.transactions.filter((transaction) => !transaction.deleted);
+    return {
+      data: transactions,
+      wasCached: false,
+      usedDelta: false,
+      serverKnowledge: response.data.server_knowledge ?? 0,
+    };
+  }
+
+  async fetchScheduledTransactions(
+    budgetId: string,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.ScheduledTransactionDetail>> {
+    const cacheKey = CacheManager.generateKey('scheduled_transactions', 'list', budgetId);
+    return await this.deltaCache.fetchWithDelta<ynab.ScheduledTransactionDetail>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response =
+          lastKnowledge !== undefined
+            ? await this.ynabAPI.scheduledTransactions.getScheduledTransactions(
+                budgetId,
+                lastKnowledge,
+              )
+            : await this.ynabAPI.scheduledTransactions.getScheduledTransactions(budgetId);
+        return {
+          data: response.data.scheduled_transactions,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeFlatEntities,
+      this.buildDeltaOptions(CACHE_TTLS.SCHEDULED_TRANSACTIONS, options),
+    );
+  }
+
+  async fetchPayees(
+    budgetId: string,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.Payee>> {
+    const cacheKey = CacheManager.generateKey('payees', 'list', budgetId);
+    return await this.deltaCache.fetchWithDelta<ynab.Payee>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response =
+          lastKnowledge !== undefined
+            ? await this.ynabAPI.payees.getPayees(budgetId, lastKnowledge)
+            : await this.ynabAPI.payees.getPayees(budgetId);
+        return {
+          data: response.data.payees,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeFlatEntities,
+      this.buildDeltaOptions(CACHE_TTLS.PAYEES, options),
+    );
+  }
+
+  async fetchMonths(
+    budgetId: string,
+    options?: DeltaFetchOptions,
+  ): Promise<DeltaFetchResult<ynab.MonthSummary>> {
+    const cacheKey = CacheManager.generateKey('months', 'list', budgetId);
+    return await this.deltaCache.fetchWithDelta<ynab.MonthSummary>(
+      cacheKey,
+      budgetId,
+      async (lastKnowledge?: number) => {
+        const response =
+          lastKnowledge !== undefined
+            ? await this.ynabAPI.months.getBudgetMonths(budgetId, lastKnowledge)
+            : await this.ynabAPI.months.getBudgetMonths(budgetId);
+        return {
+          data: response.data.months,
+          serverKnowledge: response.data.server_knowledge ?? 0,
+        };
+      },
+      mergeMonths,
+      this.buildDeltaOptions(CACHE_TTLS.MONTHS, options),
+    );
+  }
+
+  async fetchBudgets(options?: DeltaFetchOptions): Promise<DeltaFetchResult<ynab.BudgetSummary>> {
+    const cacheKey = CacheManager.generateKey('budgets', 'list');
+    const result = await this.deltaCache.fetchWithDelta<ynab.BudgetSummary & { deleted?: boolean }>(
+      cacheKey,
+      'global',
+      async () => {
+        const response = await this.ynabAPI.budgets.getBudgets();
+        const serverKnowledge =
+          (response.data as { server_knowledge?: number }).server_knowledge ?? 0;
+        return {
+          data: response.data.budgets,
+          serverKnowledge,
+        };
+      },
+      mergeFlatEntities,
+      {
+        ttl: options?.ttl ?? CACHE_TTLS.BUDGETS,
+        // TODO: Support delta responses when merge logic can handle nested objects safely.
+        forceFullRefresh: true,
+      },
+    );
+    return {
+      ...result,
+      data: result.data as ynab.BudgetSummary[],
+    };
+  }
+
+  private buildDeltaOptions(
+    defaultTtl: number,
+    options?: DeltaFetchOptions,
+  ): { ttl: number; forceFullRefresh?: boolean } {
+    return {
+      ttl: options?.ttl ?? defaultTtl,
+      ...(options?.forceFullRefresh !== undefined && {
+        forceFullRefresh: options.forceFullRefresh,
+      }),
+    };
+  }
+}

package/src/tools/deltaSupport.ts

@@ -0,0 +1,293 @@
+import * as ynab from 'ynab';
+import { cacheManager } from '../server/cacheManager.js';
+import { DeltaCache } from '../server/deltaCache.js';
+import { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import { DeltaFetcher } from './deltaFetcher.js';
+
+interface SharedDeltaSupportContext {
+  deltaFetcher?: DeltaFetcher;
+  deltaCache?: DeltaCache;
+  knowledgeStore?: ServerKnowledgeStore;
+  ynabAPI?: ynab.API;
+  manuallyConfigured?: boolean;
+}
+
+export interface SharedDeltaSupportOptions {
+  deltaFetcher?: DeltaFetcher;
+  deltaCache?: DeltaCache;
+  knowledgeStore?: ServerKnowledgeStore;
+}
+
+let sharedDeltaContext: SharedDeltaSupportContext | undefined;
+
+export function setSharedDeltaSupport(options?: SharedDeltaSupportOptions): void {
+  if (!options) {
+    sharedDeltaContext = undefined;
+    return;
+  }
+  sharedDeltaContext = {
+    ...options,
+    manuallyConfigured: true,
+  };
+}
+
+export function getSharedDeltaSupport(): SharedDeltaSupportOptions | undefined {
+  if (!sharedDeltaContext) {
+    return undefined;
+  }
+  const result: SharedDeltaSupportOptions = {};
+  if (sharedDeltaContext.deltaFetcher) {
+    result.deltaFetcher = sharedDeltaContext.deltaFetcher;
+  }
+  if (sharedDeltaContext.deltaCache) {
+    result.deltaCache = sharedDeltaContext.deltaCache;
+  }
+  if (sharedDeltaContext.knowledgeStore) {
+    result.knowledgeStore = sharedDeltaContext.knowledgeStore;
+  }
+  return result;
+}
+
+function resolveSharedDeltaFetcher(ynabAPI: ynab.API): DeltaFetcher {
+  if (
+    sharedDeltaContext &&
+    !sharedDeltaContext.manuallyConfigured &&
+    sharedDeltaContext.ynabAPI &&
+    sharedDeltaContext.ynabAPI !== ynabAPI
+  ) {
+    sharedDeltaContext = undefined;
+  }
+
+  if (sharedDeltaContext?.deltaFetcher) {
+    return sharedDeltaContext.deltaFetcher;
+  }
+
+  const context: SharedDeltaSupportContext = sharedDeltaContext ? { ...sharedDeltaContext } : {};
+  if (context.manuallyConfigured === undefined) {
+    context.manuallyConfigured = false;
+  }
+
+  if (!context.deltaCache) {
+    if (!context.knowledgeStore) {
+      context.knowledgeStore = new ServerKnowledgeStore();
+    }
+    context.deltaCache = new DeltaCache(cacheManager, context.knowledgeStore);
+  }
+
+  const deltaFetcher = new DeltaFetcher(ynabAPI, context.deltaCache);
+  context.deltaFetcher = deltaFetcher;
+  if (!context.ynabAPI) {
+    context.ynabAPI = ynabAPI;
+  }
+
+  sharedDeltaContext = context;
+
+  return deltaFetcher;
+}
+
+/**
+ * Type guard to check if a value is a DeltaFetcher instance.
+ */
+function isDeltaFetcher(value: unknown): value is DeltaFetcher {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    value instanceof DeltaFetcher &&
+    typeof (value as DeltaFetcher).fetchAccounts === 'function' &&
+    typeof (value as DeltaFetcher).fetchCategories === 'function'
+  );
+}
+
+/**
+ * Type guard to check if a value is a DeltaCache instance.
+ */
+function isDeltaCache(value: unknown): value is DeltaCache {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    value instanceof DeltaCache &&
+    typeof (value as DeltaCache).fetchWithDelta === 'function'
+  );
+}
+
+/**
+ * Type guard to check if a value is a ServerKnowledgeStore instance.
+ */
+function isServerKnowledgeStore(value: unknown): value is ServerKnowledgeStore {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    value instanceof ServerKnowledgeStore &&
+    typeof (value as ServerKnowledgeStore).get === 'function' &&
+    typeof (value as ServerKnowledgeStore).update === 'function'
+  );
+}
+
+/**
+ * Type guard to check if a value is a plain object (params).
+ */
+function isParamsObject(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    // Not a class instance
+    (value.constructor === Object || value.constructor === undefined)
+  );
+}
+
+/**
+ * Helper to get a descriptive type name for error messages.
+ */
+function getTypeName(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  const type = typeof value;
+  if (type !== 'object') return type;
+  const constructorName = (value as Record<string, unknown>).constructor?.name;
+  return constructorName ? `${type} (${constructorName})` : type;
+}
+
+export function resolveDeltaFetcherArgs<TParams extends Record<string, unknown>>(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams: DeltaFetcher | TParams,
+  maybeParams?: TParams,
+): { deltaFetcher: DeltaFetcher; params: TParams } {
+  // Case 1: Three arguments - (ynabAPI, deltaFetcher, params)
+  if (maybeParams !== undefined) {
+    // Validate that deltaFetcherOrParams is actually a DeltaFetcher
+    if (!isDeltaFetcher(deltaFetcherOrParams)) {
+      throw new Error(
+        'resolveDeltaFetcherArgs: When providing 3 arguments, the second argument must be a DeltaFetcher instance. ' +
+          `Got: ${getTypeName(deltaFetcherOrParams)}`,
+      );
+    }
+
+    // Validate that maybeParams is a params object
+    if (!isParamsObject(maybeParams)) {
+      throw new Error(
+        'resolveDeltaFetcherArgs: When providing 3 arguments, the third argument must be a params object. ' +
+          `Got: ${getTypeName(maybeParams)}`,
+      );
+    }
+
+    return {
+      deltaFetcher: deltaFetcherOrParams,
+      params: maybeParams,
+    };
+  }
+
+  // Case 2: Two arguments - (ynabAPI, params)
+  // Validate that deltaFetcherOrParams is a params object, not a DeltaFetcher
+  if (isDeltaFetcher(deltaFetcherOrParams)) {
+    throw new Error(
+      'resolveDeltaFetcherArgs: When providing 2 arguments, the second argument must be a params object, not a DeltaFetcher. ' +
+        'To use a custom DeltaFetcher, provide all 3 arguments: (ynabAPI, deltaFetcher, params)',
+    );
+  }
+
+  if (!isParamsObject(deltaFetcherOrParams)) {
+    throw new Error(
+      'resolveDeltaFetcherArgs: When providing 2 arguments, the second argument must be a params object. ' +
+        `Got: ${getTypeName(deltaFetcherOrParams)}`,
+    );
+  }
+
+  return {
+    deltaFetcher: resolveSharedDeltaFetcher(ynabAPI),
+    params: deltaFetcherOrParams,
+  };
+}
+
+export function resolveDeltaWriteArgs<TParams extends Record<string, unknown>>(
+  deltaCacheOrParams: DeltaCache | TParams,
+  knowledgeStoreOrParams?: ServerKnowledgeStore | TParams,
+  maybeParams?: TParams,
+): { deltaCache: DeltaCache; knowledgeStore: ServerKnowledgeStore; params: TParams } {
+  // Case 1: Three arguments - (deltaCache, knowledgeStore, params)
+  if (maybeParams !== undefined) {
+    // Validate that deltaCacheOrParams is actually a DeltaCache
+    if (!isDeltaCache(deltaCacheOrParams)) {
+      throw new Error(
+        'resolveDeltaWriteArgs: When providing 3 arguments, the first argument must be a DeltaCache instance. ' +
+          `Got: ${getTypeName(deltaCacheOrParams)}`,
+      );
+    }
+
+    // Validate that knowledgeStoreOrParams is actually a ServerKnowledgeStore
+    if (!isServerKnowledgeStore(knowledgeStoreOrParams)) {
+      throw new Error(
+        'resolveDeltaWriteArgs: When providing 3 arguments, the second argument must be a ServerKnowledgeStore instance. ' +
+          `Got: ${getTypeName(knowledgeStoreOrParams)}`,
+      );
+    }
+
+    // Validate that maybeParams is a params object
+    if (!isParamsObject(maybeParams)) {
+      throw new Error(
+        'resolveDeltaWriteArgs: When providing 3 arguments, the third argument must be a params object. ' +
+          `Got: ${getTypeName(maybeParams)}`,
+      );
+    }
+
+    return {
+      deltaCache: deltaCacheOrParams,
+      knowledgeStore: knowledgeStoreOrParams,
+      params: maybeParams,
+    };
+  }
+
+  // Case 2: Two arguments - could be (deltaCache, params) or just (params)
+  // Need to determine if knowledgeStoreOrParams is a ServerKnowledgeStore or params
+  if (knowledgeStoreOrParams !== undefined) {
+    const isKnowledgeStore = isServerKnowledgeStore(knowledgeStoreOrParams);
+    const isParams = isParamsObject(knowledgeStoreOrParams);
+
+    if (!isKnowledgeStore && !isParams) {
+      throw new Error(
+        'resolveDeltaWriteArgs: When providing 2 arguments, the second argument must be either a ServerKnowledgeStore or a params object. ' +
+          `Got: ${getTypeName(knowledgeStoreOrParams)}`,
+      );
+    }
+
+    // If second arg is a params object, then first arg should be params too (invalid)
+    if (isParams) {
+      throw new Error(
+        'resolveDeltaWriteArgs: Invalid argument combination. When providing 2 arguments where the second is a params object, ' +
+          'this is ambiguous. Either provide 1 argument (params only) or 3 arguments (deltaCache, knowledgeStore, params).',
+      );
+    }
+
+    // Second arg is ServerKnowledgeStore, so first arg must be DeltaCache (invalid - missing params)
+    if (isKnowledgeStore) {
+      throw new Error(
+        'resolveDeltaWriteArgs: When providing DeltaCache and ServerKnowledgeStore, you must also provide params as the third argument. ' +
+          'Got 2 arguments, expected 3: (deltaCache, knowledgeStore, params)',
+      );
+    }
+  }
+
+  // Case 3: One argument - (params)
+  // Validate that deltaCacheOrParams is a params object, not a DeltaCache
+  if (isDeltaCache(deltaCacheOrParams)) {
+    throw new Error(
+      'resolveDeltaWriteArgs: When providing only 1 argument, it must be a params object, not a DeltaCache. ' +
+        'To use a custom DeltaCache, provide all 3 arguments: (deltaCache, knowledgeStore, params)',
+    );
+  }
+
+  if (!isParamsObject(deltaCacheOrParams)) {
+    throw new Error(
+      'resolveDeltaWriteArgs: When providing only 1 argument, it must be a params object. ' +
+        `Got: ${getTypeName(deltaCacheOrParams)}`,
+    );
+  }
+
+  const fallbackKnowledgeStore = new ServerKnowledgeStore();
+  const fallbackDeltaCache = new DeltaCache(cacheManager, fallbackKnowledgeStore);
+  return {
+    deltaCache: fallbackDeltaCache,
+    knowledgeStore: fallbackKnowledgeStore,
+    params: deltaCacheOrParams,
+  };
+}