@dilllxd/simplefin-cli 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# 🪙 simplefin-cli
+
+[![npm version](https://img.shields.io/npm/v/%40dilllxd/simplefin-cli?color=blue)](https://www.npmjs.com/package/@dilllxd/simplefin-cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green?logo=node.js)](https://nodejs.org)
+
+A CLI tool for accessing financial data via [SimpleFIN Bridge](https://beta-bridge.simplefin.org/).
+
+---
+
+## ✨ Why simplefin-cli?
+
+[SimpleFIN Bridge](https://beta-bridge.simplefin.org/) provides a secure way to access financial data.
+`simplefin-cli` gives you full command-line access without a GUI.
+
+✅ Non-interactive (100% automatable)
+✅ Cross-platform (Linux, macOS, Windows)
+✅ Full SimpleFIN protocol support
+✅ JSON output for scripting
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install -g @dilllxd/simplefin-cli
+```
+
+---
+
+## 💡 Quick Start
+
+```bash
+# Connect with a setup token
+simplefin connect --token YOUR_SETUP_TOKEN
+
+# List accounts
+simplefin accounts
+
+# View transactions
+simplefin transactions
+
+# Get transactions as JSON
+simplefin transactions --json
+```
+
+Get a setup token at https://beta-bridge.simplefin.org/my-account/tokens/create
+
+---
+
+## 📖 Commands
+
+### `simplefin connect`
+
+Connect to SimpleFIN Bridge using a setup token.
+
+```bash
+simplefin connect --token <setup-token>
+```
+
+Token can also be provided via `SIMPLEFIN_SETUP_TOKEN` environment variable.
+
+---
+
+### `simplefin disconnect`
+
+Remove saved credentials.
+
+```bash
+simplefin disconnect
+```
+
+---
+
+### `simplefin status`
+
+Check connection status.
+
+```bash
+simplefin status
+simplefin status --json
+```
+
+---
+
+### `simplefin accounts`
+
+List connected accounts.
+
+```bash
+simplefin accounts
+simplefin accounts --json
+simplefin accounts --balances-only
+```
+
+---
+
+### `simplefin transactions`
+
+List transactions.
+
+```bash
+simplefin transactions                        # Last 30 days
+simplefin transactions --days 7               # Last 7 days
+simplefin transactions --json                 # JSON output
+simplefin transactions --start-date 2026-01-01
+simplefin transactions --end-date 2026-01-31
+simplefin transactions --account ACT-12345
+simplefin transactions --pending
+```
+
+---
+
+### `simplefin info`
+
+Show server information.
+
+```bash
+simplefin info
+simplefin info --json
+```
+
+---
+
+## 🔧 Configuration
+
+Credentials stored in OS-appropriate location:
+
+| OS | Location |
+|---|---|
+| Linux | `~/.config/simplefin-cli/connection.json` |
+| macOS | `~/Library/Application Support/simplefin-cli/` |
+| Windows | `%APPDATA%\simplefin-cli\` |
+
+---
+
+## 🧱 Project Structure
+
+```
+simplefin-cli/
+├── bin/
+│   └── simplefin.js    # Main CLI entry point
+├── LICENSE
+├── package.json
+└── README.md
+```
+
+---
+
+## 🪪 License
+
+MIT

package/bin/simplefin.js

@@ -0,0 +1,454 @@
+const { Command } = require('commander');
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const program = new Command();
+
+function getConfigDir() {
+  const appName = 'simplefin-cli';
+  
+  switch (process.platform) {
+    case 'darwin': // macOS
+      return path.join(os.homedir(), 'Library', 'Application Support', appName);
+    case 'win32': // Windows
+      return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), appName);
+    default: // Linux, BSD, etc.
+      if (process.env.XDG_CONFIG_HOME) {
+        return path.join(process.env.XDG_CONFIG_HOME, appName);
+      }
+      return path.join(os.homedir(), '.config', appName);
+  }
+}
+
+function getConnectionPath() {
+  return path.join(getConfigDir(), 'connection.json');
+}
+
+function loadConnection() {
+  try {
+    const data = fs.readFileSync(getConnectionPath(), 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+function saveConnection(accessUrl, username, password) {
+  fs.mkdirSync(getConfigDir(), { recursive: true });
+  const connection = {
+    access_url: accessUrl,
+    username,
+    password,
+    created_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(getConnectionPath(), JSON.stringify(connection, null, 2));
+}
+
+function deleteConnection() {
+  try {
+    fs.unlinkSync(getConnectionPath());
+  } catch (e) {
+    // ignore
+  }
+}
+
+function parseAuthFromUrl(accessUrl) {
+  const match = accessUrl.match(/:\/\/([^:]+):([^@]+)@/);
+  if (match) {
+    return {
+      username: match[1],
+      password: match[2],
+      baseUrl: accessUrl.replace(/:\/\/[^:]+:[^@]+@/, '://'),
+    };
+  }
+  return null;
+}
+
+async function claimAccessUrl(setupToken) {
+  const claimUrl = Buffer.from(setupToken, 'base64').toString('utf-8');
+  
+  const response = await axios.post(claimUrl, '', {
+    headers: { 'Content-Length': '0' },
+    timeout: 10000,
+  });
+
+  if (response.status === 403) {
+    throw new Error('Token is invalid or has already been used');
+  }
+
+  if (response.status !== 200) {
+    throw new Error(`Unexpected response: ${response.status}`);
+  }
+
+  const accessUrl = response.data.trim();
+  if (!accessUrl) {
+    throw new Error('Empty response from server');
+  }
+
+  return accessUrl;
+}
+
+async function getInfo(baseUrl) {
+  const response = await axios.get(`${baseUrl}/info`);
+  return response.data;
+}
+
+async function getAccounts(options) {
+  const params = new URLSearchParams();
+  
+  if (options.startDate) params.append('start-date', options.startDate);
+  if (options.endDate) params.append('end-date', options.endDate);
+  if (options.pending) params.append('pending', '1');
+  if (options.account) params.append('account', options.account);
+  if (options.balancesOnly) params.append('balances-only', '1');
+  
+  const url = `${options.baseUrl}/accounts${params.toString() ? '?' + params.toString() : ''}`;
+  
+  const response = await axios.get(url, {
+    auth: { username: options.username, password: options.password },
+  });
+
+  if (response.status === 403) {
+    throw new Error('Authentication failed - access may be revoked');
+  }
+
+  if (response.status === 402) {
+    throw new Error('Payment required');
+  }
+
+  return response.data;
+}
+
+function formatDate(timestamp) {
+  if (!timestamp) return 'N/A';
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleString('en-US', {
+    month: 'short', day: 'numeric', year: 'numeric',
+    hour: 'numeric', minute: '2-digit', hour12: true,
+  });
+}
+
+function formatDateFull(timestamp) {
+  if (!timestamp) return 'N/A';
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleString('en-US', {
+    weekday: 'short', month: 'short', day: 'numeric', year: 'numeric',
+    hour: 'numeric', minute: '2-digit', hour12: true,
+  });
+}
+
+function formatDateShort(timestamp) {
+  if (!timestamp) return '';
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleDateString('en-US', { month: '2-digit', day: '2-digit' });
+}
+
+function truncate(str, len) {
+  if (!str) return '';
+  return str.length > len ? str.slice(0, len - 3) + '...' : str;
+}
+
+program.name('simplefin').description('SimpleFIN CLI - Access your financial data');
+
+// ===== INFO COMMAND =====
+program.command('info')
+  .description('Get SimpleFIN server information')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      console.log("Run 'simplefin connect' first");
+      process.exit(1);
+    }
+    
+    try {
+      const data = await getInfo(conn.access_url);
+      
+      if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      
+      console.log('Server Info');
+      console.log('-----------');
+      console.log(`Supported versions: ${(data.versions || []).join(', ')}`);
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ===== CONNECT COMMAND =====
+program.command('connect')
+  .description('Connect to SimpleFIN Bridge')
+  .option('-t, --token <token>', 'Setup token (or use SIMPLEFIN_SETUP_TOKEN env var)')
+  .action(async (options) => {
+    let setupToken = options.token || process.env.SIMPLEFIN_SETUP_TOKEN;
+    
+    if (!setupToken) {
+      console.log('Error: Setup token required');
+      console.log('Provide via:');
+      console.log('  -t, --token option: simplefin connect --token <token>');
+      console.log('  Environment variable: export SIMPLEFIN_SETUP_TOKEN=<token>');
+      console.log('\nGet a token at: https://bridge.simplefin.org/simplefin/create');
+      process.exit(1);
+    }
+    
+    console.log('Connecting to SimpleFIN Bridge...');
+    
+    try {
+      const accessUrl = await claimAccessUrl(setupToken);
+      const auth = parseAuthFromUrl(accessUrl);
+      if (!auth) {
+        throw new Error('Could not parse credentials from Access URL');
+      }
+      saveConnection(auth.baseUrl, auth.username, auth.password);
+      console.log('Connected successfully!');
+      console.log('\nNext steps:');
+      console.log('  simplefin info         - Server info');
+      console.log('  simplefin accounts     - List your accounts');
+      console.log('  simplefin transactions - View transactions');
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ===== DISCONNECT COMMAND =====
+program.command('disconnect')
+  .description('Disconnect from SimpleFIN Bridge')
+  .action(() => {
+    deleteConnection();
+    console.log('Disconnected successfully');
+  });
+
+// ===== STATUS COMMAND =====
+program.command('status')
+  .description('Check connection status')
+  .option('--json', 'Output as JSON')
+  .action((options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      console.log("Run 'simplefin connect' first");
+      process.exit(1);
+    }
+    
+    if (options.json) {
+      console.log(JSON.stringify({
+        connected: true,
+        server: conn.access_url,
+        created_at: conn.created_at,
+      }, null, 2));
+      return;
+    }
+    
+    console.log('Connection Status');
+    console.log('-----------------');
+    console.log('Connected');
+    console.log(`Server: ${conn.access_url}`);
+    console.log(`Connected since: ${formatDate(new Date(conn.created_at).getTime() / 1000)}`);
+  });
+
+// ===== ACCOUNTS COMMAND =====
+program.command('accounts')
+  .description('List all connected accounts')
+  .option('--json', 'Output as JSON')
+  .option('--balances-only', 'Only show balances, no transactions')
+  .action(async (options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      process.exit(1);
+    }
+    
+    try {
+      const data = await getAccounts({
+        baseUrl: conn.access_url,
+        username: conn.username,
+        password: conn.password,
+        balancesOnly: options.balancesOnly,
+      });
+      
+      if (data.errors && data.errors.length > 0) {
+        console.log('Errors from server:');
+        for (const err of data.errors) {
+          console.log(`  - ${err}`);
+        }
+        console.log('');
+      }
+      
+      const accounts = data.accounts || [];
+      
+      if (options.json) {
+        console.log(JSON.stringify({
+          connected: true,
+          errors: data.errors || [],
+          accounts: accounts.map(acc => ({
+            id: acc.id,
+            name: acc.name,
+            organization: acc.org?.name || acc.org?.domain || 'Unknown',
+            balance: acc.balance,
+            'available-balance': acc['available-balance'],
+            currency: acc.currency,
+            'balance-date': acc['balance-date'],
+            type: acc.type,
+            extra: acc.extra,
+          })),
+          total_accounts: accounts.length,
+        }, null, 2));
+        return;
+      }
+      
+      console.log('Accounts');
+      console.log('--------');
+      for (const acc of accounts) {
+        console.log(`${acc.name} (${acc.org?.name || acc.org?.domain || 'Unknown'})`);
+        console.log(`  Balance: ${acc.balance} ${acc.currency}`);
+        if (acc['available-balance'] && acc['available-balance'] !== acc.balance) {
+          console.log(`  Available: ${acc['available-balance']} ${acc.currency}`);
+        }
+        console.log(`  Last updated: ${formatDate(acc['balance-date'])}`);
+        if (acc.type) {
+          console.log(`  Type: ${acc.type}`);
+        }
+        if (acc.transactions && acc.transactions.length > 0 && !options.balancesOnly) {
+          console.log(`  Transactions: ${acc.transactions.length}`);
+        }
+      }
+      console.log('--------');
+      console.log(`Total: ${accounts.length} account(s)`);
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ===== TRANSACTIONS COMMAND =====
+program.command('transactions')
+  .description('List transactions')
+  .option('-d, --days <days>', 'Number of days to look back', '30')
+  .option('--start-date <date>', 'Start date (Unix timestamp or YYYY-MM-DD)')
+  .option('--end-date <date>', 'End date (Unix timestamp or YYYY-MM-DD)')
+  .option('--account <id>', 'Filter by account ID')
+  .option('--pending', 'Include pending transactions')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      process.exit(1);
+    }
+    
+    // Parse dates
+    let startDate, endDate;
+    
+    if (options.startDate) {
+      if (options.startDate.includes('-')) {
+        startDate = Math.floor(new Date(options.startDate).getTime() / 1000);
+      } else {
+        startDate = parseInt(options.startDate);
+      }
+    } else {
+      const days = parseInt(options.days) || 30;
+      startDate = Math.floor(Date.now() / 1000) - (days * 24 * 60 * 60);
+    }
+    
+    if (options.endDate) {
+      if (options.endDate.includes('-')) {
+        endDate = Math.floor(new Date(options.endDate).getTime() / 1000);
+      } else {
+        endDate = parseInt(options.endDate);
+      }
+    }
+    
+    try {
+      const data = await getAccounts({
+        baseUrl: conn.access_url,
+        username: conn.username,
+        password: conn.password,
+        startDate: startDate.toString(),
+        endDate: endDate?.toString(),
+        account: options.account,
+        pending: options.pending,
+      });
+      
+      if (data.errors && data.errors.length > 0) {
+        console.log('Errors from server:');
+        for (const err of data.errors) {
+          console.log(`  - ${err}`);
+        }
+        console.log('');
+      }
+      
+      const accounts = data.accounts || [];
+      const allTransactions = [];
+      
+      for (const acc of accounts) {
+        for (const tx of acc.transactions || []) {
+          allTransactions.push({
+            ...tx,
+            account_name: acc.name,
+            account_id: acc.id,
+          });
+        }
+      }
+      
+      allTransactions.sort((a, b) => b.posted - a.posted);
+      
+      if (options.json) {
+        console.log(JSON.stringify({
+          connected: true,
+          errors: data.errors || [],
+          query: {
+            start_date: startDate,
+            end_date: endDate,
+            account: options.account,
+            pending: options.pending,
+          },
+          transactions: allTransactions,
+          count: allTransactions.length,
+        }, null, 2));
+        return;
+      }
+      
+      console.log('Transactions');
+      console.log('------------');
+      
+      if (startDate && !options.startDate) {
+        const days = parseInt(options.days) || 30;
+        console.log(`From last ${days} days`);
+      } else if (startDate) {
+        console.log(`From ${formatDate(startDate)}`);
+        if (endDate) console.log(`To ${formatDate(endDate)}`);
+      }
+      
+      console.log(`Found ${allTransactions.length} transaction(s)\n`);
+      
+      for (const tx of allTransactions) {
+        const amount = parseFloat(tx.amount).toFixed(2);
+        const sign = tx.amount.startsWith('-') ? '' : '+';
+        const pending = tx.pending ? '[PENDING] ' : '';
+        const date = tx.posted ? formatDateFull(tx.posted) : 'N/A';
+        
+        console.log(`${date}`);
+        console.log(`  ${sign}${amount.padStart(10)}  ${pending}${truncate(tx.description, 50)}`);
+        console.log(`  Account: ${tx.account_name}`);
+        if (tx.transacted_at && tx.transacted_at !== tx.posted) {
+          console.log(`  Transacted: ${formatDateFull(tx.transacted_at)}`);
+        }
+        if (tx.category || (tx.extra && tx.extra.category)) {
+          console.log(`  Category: ${tx.category || tx.extra.category}`);
+        }
+        console.log('');
+      }
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dilllxd/simplefin-cli",
+  "version": "0.1.0",
+  "description": "CLI tool for accessing financial data via SimpleFIN Bridge",
+  "author": "dilllxd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.dylan.lol/dylan/cli-tools"
+  },
+  "bugs": {
+    "url": "https://git.dylan.lol/dylan/cli-tools/issues"
+  },
+  "homepage": "https://git.dylan.lol/dylan/cli-tools/tree/main/simplefin-cli",
+  "keywords": [
+    "simplefin",
+    "finance",
+    "bank",
+    "cli",
+    "terminal"
+  ],
+  "bin": {
+    "simplefin": "./bin/simplefin.js"
+  },
+  "files": [
+    "bin/",
+    "LICENSE"
+  ],
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "x86",
+    "arm64",
+    "armv7l"
+  ],
+  "dependencies": {
+    "axios": "1.6.0",
+    "commander": "11.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}