market_screener/server/finance/clients/SimpleFINClient.ts

import fs from 'fs';
import https from 'https';
import http from 'http';
import type { Logger } from '../../types.js';

interface SimpleFINOptions {
  logger?: Logger;
  onAccessUrlClaimed?: (url: string) => Promise<void> | void;
}

interface GetAccountsOptions {
  startDate?: number;
  endDate?: number;
}

interface Transaction {
  id: string;
  date: string;
  amount: number;
  description: string;
  category: string;
}

interface Account {
  id: string;
  name: string;
  currency: string;
  balance: number;
  balanceDate: string;
  org: string;
  type: string;
  transactions: Transaction[];
}

interface SimpleFINData {
  accounts: Account[];
  errors: string[];
}

export class SimpleFINClient {
  private accessUrl: string | null;
  private logger: Logger;
  private onAccessUrlClaimed: ((url: string) => Promise<void> | void) | null;

  constructor({ logger, onAccessUrlClaimed }: SimpleFINOptions = {}) {
    this.accessUrl = null;
    this.logger = logger ?? {
      write: (msg) => process.stdout.write(msg),
      log: (...args) => console.log(...args),
      warn: (...args) => console.warn(...args),
    };
    this.onAccessUrlClaimed = onAccessUrlClaimed ?? null;
  }

  async init(): Promise<void> {
    if (process.env.SIMPLEFIN_ACCESS_URL) {
      this.accessUrl = process.env.SIMPLEFIN_ACCESS_URL.replace(/\/$/, '');
      return;
    }
    if (process.env.SIMPLEFIN_SETUP_TOKEN) {
      this.accessUrl = await this._claimAccessUrl(process.env.SIMPLEFIN_SETUP_TOKEN);
      if (this.onAccessUrlClaimed) await this.onAccessUrlClaimed(this.accessUrl);
      return;
    }
    throw new Error(
      'SimpleFIN not configured.\nAdd to .env:\n  SIMPLEFIN_SETUP_TOKEN=<your setup token from https://beta-bridge.simplefin.org>\nThe Access URL will be saved automatically on first run.',
    );
  }

  async getAccounts(options: GetAccountsOptions = {}): Promise<SimpleFINData> {
    if (!this.accessUrl) await this.init();

    const startDate = options.startDate ?? this._daysAgo(30);
    const endDate = options.endDate ?? Math.floor(Date.now() / 1000);

    const parsed = new URL(this.accessUrl!);
    const auth = parsed.username
      ? 'Basic ' + Buffer.from(`${parsed.username}:${parsed.password}`).toString('base64')
      : null;
    parsed.username = '';
    parsed.password = '';
    const cleanBase = parsed.toString().replace(/\/$/, '');

    const url = `${cleanBase}/accounts?version=2&start-date=${startDate}&end-date=${endDate}`;
    const response = await fetch(url, { headers: auth ? { Authorization: auth } : {} });

    if (!response.ok) {
      throw new Error(`SimpleFIN error ${response.status}: ${await response.text()}`);
    }

    const data = (await response.json()) as { accounts?: unknown[]; errors?: string[] };
    if (data.errors?.length) {
      data.errors.forEach((e) => this.logger.warn(`  ⚠ SimpleFIN: ${e}`));
    }

    return this._normalise(data as { accounts: unknown[]; errors: string[] });
  }

  private async _claimAccessUrl(setupToken: string): Promise<string> {
    const claimUrl = Buffer.from(setupToken.trim(), 'base64').toString('utf8').trim();
    this.logger.write(`\n🔑 Claiming SimpleFIN access URL...\n   → ${claimUrl}\n`);
    const accessUrl = await this._post(claimUrl);
    if (!accessUrl || !accessUrl.startsWith('http')) {
      throw new Error(
        `Unexpected response from SimpleFIN: "${accessUrl}"\nSetup tokens are one-time use — if already claimed, generate a new one at https://beta-bridge.simplefin.org`,
      );
    }
    this.logger.write('✅ Access URL received\n');
    return accessUrl.trim();
  }

  private _post(url: string): Promise<string> {
    return new Promise((resolve, reject) => {
      const parsed = new URL(url);
      const lib = parsed.protocol === 'https:' ? https : http;
      const options = {
        hostname: parsed.hostname,
        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
        path: parsed.pathname + parsed.search,
        method: 'POST',
        headers: { 'Content-Length': '0', 'Content-Type': 'application/x-www-form-urlencoded' },
      };
      const req = lib.request(options, (res) => {
        let body = '';
        res.on('data', (chunk: string) => {
          body += chunk;
        });
        res.on('end', () => {
          if ((res.statusCode ?? 0) >= 200 && (res.statusCode ?? 0) < 300) resolve(body.trim());
          else reject(new Error(`HTTP ${res.statusCode}: ${body.trim()}`));
        });
      });
      req.on('error', reject);
      req.end();
    });
  }

  private _normalise(data: { accounts: unknown[]; errors: string[] }): SimpleFINData {
    const accounts = (data.accounts ?? []).map((acc: any) => ({
      id: acc.id,
      name: acc.name,
      currency: acc.currency ?? 'USD',
      balance: parseFloat(acc.balance) ?? 0,
      balanceDate: new Date(acc['balance-date'] * 1000).toISOString().slice(0, 10),
      org: acc.org?.name ?? 'Unknown',
      type: this._classifyAccount(acc.name),
      transactions: (acc.transactions ?? []).map((tx: any) => ({
        id: tx.id,
        date: new Date(tx.posted * 1000).toISOString().slice(0, 10),
        amount: parseFloat(tx.amount) ?? 0,
        description: tx.description ?? '',
        category: this._categorise(tx.description ?? ''),
      })),
    }));
    return { accounts, errors: data.errors ?? [] };
  }

  private _classifyAccount(name: string): string {
    const n = name.toLowerCase();
    if (n.includes('checking') || n.includes('current')) return 'CHECKING';
    if (n.includes('saving')) return 'SAVINGS';
    if (n.includes('credit') || n.includes('card')) return 'CREDIT';
    if (n.includes('invest') || n.includes('brokerage') || n.includes('401k') || n.includes('ira'))
      return 'INVESTMENT';
    if (n.includes('loan') || n.includes('mortgage')) return 'LOAN';
    return 'OTHER';
  }

  private _categorise(description: string): string {
    const d = description.toLowerCase();
    if (d.match(/amazon|walmart|target|costco|grocery|whole foods|trader joe/)) return 'Shopping';
    if (d.match(/uber eats|doordash|grubhub|postmates|instacart/)) return 'Delivery';
    if (d.match(/netflix|spotify|apple|disney|hulu|youtube/)) return 'Subscriptions';
    if (d.match(/restaurant|cafe|coffee|starbucks|chipotle|mcdonald/)) return 'Dining';
    if (d.match(/shell|chevron|bp|exxon|fuel|gas station/)) return 'Gas';
    if (d.match(/uber|lyft|transit|mta|bart|metro/)) return 'Transport';
    if (d.match(/rent|mortgage|hoa|property/)) return 'Housing';
    if (d.match(/electric|water|internet|phone|at&t|verizon|comcast/)) return 'Utilities';
    if (d.match(/payroll|salary|direct deposit/)) return 'Income';
    if (d.match(/transfer|zelle|venmo|paypal/)) return 'Transfer';
    return 'Other';
  }

  private _daysAgo(n: number): number {
    return Math.floor((Date.now() - n * 24 * 60 * 60 * 1000) / 1000);
  }
}

export function saveAccessUrlToEnv(accessUrl: string): void {
  try {
    const existing = fs.existsSync('.env') ? fs.readFileSync('.env', 'utf8') : '';
    if (!existing.includes('SIMPLEFIN_ACCESS_URL')) {
      fs.appendFileSync('.env', `\nSIMPLEFIN_ACCESS_URL=${accessUrl}\n`);
      console.log('✅ Access URL saved to .env — you can remove SIMPLEFIN_SETUP_TOKEN\n');
    }
  } catch {
    console.log(`\nSave this to .env:\nSIMPLEFIN_ACCESS_URL=${accessUrl}\n`);
  }
}