sheetlink 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "sheetlink",
+  "version": "0.1.0",
+  "description": "CLI for SheetLink — sync your bank transactions to any destination",
+  "type": "module",
+  "bin": {
+    "sheetlink": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "open": "^10.1.0",
+    "pg": "^8.13.3",
+    "better-sqlite3": "^11.9.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "sheetlink",
+    "plaid",
+    "finance",
+    "banking",
+    "transactions",
+    "cli"
+  ],
+  "author": "Rudy Martin Del Campo <rudy@sheetlink.app>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheetlink/sheetlink-client"
+  }
+}

package/src/adapters/csv.js

@@ -0,0 +1,45 @@
+/**
+ * csv.js - CSV snapshot adapter
+ *
+ * Writes a flat snapshot of transactions to a CSV file.
+ * Each run OVERWRITES the file — no append, no dedup.
+ * Users who want history should use Postgres or SQLite.
+ */
+
+import fs from 'fs';
+
+const HEADERS = [
+  'date',
+  'name',
+  'amount',
+  'category',
+  'account_id',
+  'account_name',
+  'account_mask',
+  'institution_name',
+  'pending',
+  'payment_channel',
+  'merchant_name',
+  'primary_category',
+  'detailed_category',
+  'transaction_id',
+];
+
+function escape(val) {
+  if (val === null || val === undefined) return '';
+  const s = String(val);
+  if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+function formatRow(txn) {
+  return HEADERS.map(h => escape(txn[h])).join(',');
+}
+
+export function writeCsv(transactions, filePath = './sheetlink-transactions.csv') {
+  const lines = [HEADERS.join(','), ...transactions.map(formatRow)];
+  fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf8');
+  console.error(`Wrote ${transactions.length} transactions to ${filePath}`);
+}

package/src/adapters/json.js

@@ -0,0 +1,10 @@
+/**
+ * json.js - JSON stdout adapter
+ *
+ * Writes full sync result to stdout as JSON.
+ * Pipeable: sheetlink sync | jq '.transactions[] | select(.amount > 100)'
+ */
+
+export function writeJson(result) {
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}

package/src/adapters/postgres.js

@@ -0,0 +1,98 @@
+/**
+ * postgres.js - Postgres upsert adapter (MAX tier only)
+ *
+ * Creates sheetlink_transactions and sheetlink_accounts tables if they don't exist.
+ * Upserts on primary key — safe to run repeatedly with no duplicates.
+ */
+
+const CREATE_TRANSACTIONS = `
+CREATE TABLE IF NOT EXISTS sheetlink_transactions (
+  transaction_id TEXT PRIMARY KEY,
+  date DATE NOT NULL,
+  name TEXT,
+  amount DECIMAL(10,2),
+  category TEXT,
+  account_id TEXT,
+  account_name TEXT,
+  account_mask TEXT,
+  institution_name TEXT,
+  pending BOOLEAN,
+  payment_channel TEXT,
+  merchant_name TEXT,
+  primary_category TEXT,
+  detailed_category TEXT,
+  synced_at TIMESTAMP DEFAULT NOW()
+)`;
+
+const CREATE_ACCOUNTS = `
+CREATE TABLE IF NOT EXISTS sheetlink_accounts (
+  account_id TEXT PRIMARY KEY,
+  name TEXT,
+  mask TEXT,
+  type TEXT,
+  subtype TEXT,
+  balance_current DECIMAL(10,2),
+  balance_available DECIMAL(10,2),
+  institution_name TEXT,
+  last_synced_at TIMESTAMP DEFAULT NOW()
+)`;
+
+const UPSERT_TRANSACTION = `
+INSERT INTO sheetlink_transactions
+  (transaction_id, date, name, amount, category, account_id, account_name, account_mask,
+   institution_name, pending, payment_channel, merchant_name, primary_category, detailed_category, synced_at)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,NOW())
+ON CONFLICT (transaction_id) DO UPDATE SET
+  date = EXCLUDED.date,
+  name = EXCLUDED.name,
+  amount = EXCLUDED.amount,
+  category = EXCLUDED.category,
+  pending = EXCLUDED.pending,
+  synced_at = NOW()`;
+
+const UPSERT_ACCOUNT = `
+INSERT INTO sheetlink_accounts
+  (account_id, name, mask, type, subtype, balance_current, balance_available, institution_name, last_synced_at)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8,NOW())
+ON CONFLICT (account_id) DO UPDATE SET
+  name = EXCLUDED.name,
+  balance_current = EXCLUDED.balance_current,
+  balance_available = EXCLUDED.balance_available,
+  last_synced_at = NOW()`;
+
+export async function writePostgres(transactions, accounts, connectionString) {
+  // Dynamic import so users without pg installed don't hit an error on other commands
+  const { default: pg } = await import('pg').then(m => ({ default: m.default || m }));
+  const { Client } = pg;
+
+  const client = new Client({ connectionString });
+  await client.connect();
+
+  try {
+    await client.query(CREATE_TRANSACTIONS);
+    await client.query(CREATE_ACCOUNTS);
+
+    for (const tx of transactions) {
+      await client.query(UPSERT_TRANSACTION, [
+        tx.transaction_id, tx.date, tx.name, tx.amount, tx.category,
+        tx.account_id, tx.account_name, tx.account_mask,
+        tx.institution_name || tx.source_institution,
+        tx.pending, tx.payment_channel, tx.merchant_name,
+        tx.primary_category, tx.detailed_category,
+      ]);
+    }
+
+    for (const acc of accounts) {
+      await client.query(UPSERT_ACCOUNT, [
+        acc.account_id, acc.name, acc.mask, acc.type, acc.subtype,
+        acc.balances?.current ?? null,
+        acc.balances?.available ?? null,
+        acc.institution || acc.institution_name || null,
+      ]);
+    }
+
+    console.error(`Synced ${transactions.length} transactions and ${accounts.length} accounts to Postgres`);
+  } finally {
+    await client.end();
+  }
+}

package/src/adapters/sqlite.js

@@ -0,0 +1,95 @@
+/**
+ * sqlite.js - SQLite upsert adapter (MAX tier only)
+ *
+ * Same schema as Postgres. Upserts on primary key — safe to run repeatedly.
+ */
+
+const CREATE_TRANSACTIONS = `
+CREATE TABLE IF NOT EXISTS sheetlink_transactions (
+  transaction_id TEXT PRIMARY KEY,
+  date TEXT NOT NULL,
+  name TEXT,
+  amount REAL,
+  category TEXT,
+  account_id TEXT,
+  account_name TEXT,
+  account_mask TEXT,
+  institution_name TEXT,
+  pending INTEGER,
+  payment_channel TEXT,
+  merchant_name TEXT,
+  primary_category TEXT,
+  detailed_category TEXT,
+  synced_at TEXT DEFAULT (datetime('now'))
+)`;
+
+const CREATE_ACCOUNTS = `
+CREATE TABLE IF NOT EXISTS sheetlink_accounts (
+  account_id TEXT PRIMARY KEY,
+  name TEXT,
+  mask TEXT,
+  type TEXT,
+  subtype TEXT,
+  balance_current REAL,
+  balance_available REAL,
+  institution_name TEXT,
+  last_synced_at TEXT DEFAULT (datetime('now'))
+)`;
+
+const UPSERT_TRANSACTION = `
+INSERT INTO sheetlink_transactions
+  (transaction_id, date, name, amount, category, account_id, account_name, account_mask,
+   institution_name, pending, payment_channel, merchant_name, primary_category, detailed_category, synced_at)
+VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,datetime('now'))
+ON CONFLICT(transaction_id) DO UPDATE SET
+  date=excluded.date, name=excluded.name, amount=excluded.amount,
+  category=excluded.category, pending=excluded.pending, synced_at=datetime('now')`;
+
+const UPSERT_ACCOUNT = `
+INSERT INTO sheetlink_accounts
+  (account_id, name, mask, type, subtype, balance_current, balance_available, institution_name, last_synced_at)
+VALUES (?,?,?,?,?,?,?,?,datetime('now'))
+ON CONFLICT(account_id) DO UPDATE SET
+  name=excluded.name, balance_current=excluded.balance_current,
+  balance_available=excluded.balance_available, last_synced_at=datetime('now')`;
+
+export async function writeSQLite(transactions, accounts, dbPath) {
+  // Dynamic import so users without better-sqlite3 don't hit an error on other commands
+  const Database = (await import('better-sqlite3')).default;
+
+  const db = new Database(dbPath);
+  db.exec(CREATE_TRANSACTIONS);
+  db.exec(CREATE_ACCOUNTS);
+
+  const insertTx = db.prepare(UPSERT_TRANSACTION);
+  const insertAcc = db.prepare(UPSERT_ACCOUNT);
+
+  const txBatch = db.transaction((txns) => {
+    for (const tx of txns) {
+      insertTx.run(
+        tx.transaction_id, tx.date, tx.name, tx.amount, tx.category,
+        tx.account_id, tx.account_name, tx.account_mask,
+        tx.institution_name || tx.source_institution,
+        tx.pending ? 1 : 0, tx.payment_channel, tx.merchant_name,
+        tx.primary_category, tx.detailed_category,
+      );
+    }
+  });
+
+  const accBatch = db.transaction((accs) => {
+    for (const acc of accs) {
+      insertAcc.run(
+        acc.account_id, acc.name, acc.mask, acc.type, acc.subtype,
+        acc.balances?.current ?? null,
+        acc.balances?.available ?? null,
+        acc.institution || acc.institution_name || null,
+      );
+    }
+  });
+
+  txBatch(transactions);
+  accBatch(accounts);
+  db.close();
+
+  console.error(`Synced ${transactions.length} transactions and ${accounts.length} accounts to ${dbPath}`);
+}

package/src/api.js

@@ -0,0 +1,60 @@
+/**
+ * api.js - SheetLink API client
+ *
+ * Thin wrapper around fetch for the SheetLink backend.
+ * All endpoints require Authorization: Bearer <token>.
+ */
+
+import { getApiUrl, getAuthHeader } from './config.js';
+
+async function request(method, path, body = null) {
+  const auth = getAuthHeader();
+  if (!auth) {
+    console.error('Not authenticated. Run `sheetlink auth` to set up credentials.');
+    process.exit(1);
+  }
+
+  const url = `${getApiUrl()}${path}`;
+  const opts = {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': auth,
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+
+  const res = await fetch(url, opts);
+
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      const err = await res.json();
+      detail = err.detail || JSON.stringify(err);
+    } catch {}
+
+    if (res.status === 401) {
+      console.error('Authentication failed. Run `sheetlink auth` to re-authenticate.');
+      process.exit(1);
+    }
+    if (res.status === 403) {
+      console.error(`Access denied: ${detail}`);
+      process.exit(1);
+    }
+    throw new Error(`API error ${res.status}: ${detail}`);
+  }
+
+  return res.json();
+}
+
+export async function listItems() {
+  return request('GET', '/api/items');
+}
+
+export async function syncItem(itemId) {
+  return request('POST', '/api/sync', { item_id: itemId });
+}
+
+export async function getTierStatus() {
+  return request('GET', '/tier/status');
+}

package/src/commands/auth.js

@@ -0,0 +1,165 @@
+/**
+ * auth.js - `sheetlink auth`
+ *
+ * Two paths:
+ *   API key (MAX):  `sheetlink auth --api-key sl_...`
+ *                   Stores key in ~/.sheetlink/config.json
+ *
+ *   OAuth (PRO):    `sheetlink auth`
+ *                   Opens Google OAuth in browser, exchanges for JWT,
+ *                   stores JWT in config file.
+ *
+ * Note: PRO JWT auth is interactive only — tokens expire ~1hr.
+ * For unattended automation, use MAX tier + API key.
+ */
+
+import http from 'http';
+import { randomBytes } from 'crypto';
+import { writeConfig, getApiUrl } from '../config.js';
+import { getTierStatus } from '../api.js';
+
+const GOOGLE_CLIENT_ID = '967710910027-qq2tuel7vsi2i06h4h096hbvok8kfmhk.apps.googleusercontent.com';
+const REDIRECT_PORT = 9876;
+const REDIRECT_URI = `http://localhost:${REDIRECT_PORT}/callback`;
+
+export async function cmdAuth(options) {
+  // --- API key path ---
+  if (options.apiKey) {
+    if (!options.apiKey.startsWith('sl_')) {
+      console.error('Invalid API key format. Keys should start with sl_');
+      process.exit(1);
+    }
+
+    // Warn about shell history exposure
+    console.error('');
+    console.error('Security note: API keys passed via --api-key may appear in your shell history.');
+    console.error('Consider setting SHEETLINK_API_KEY as an environment variable instead:');
+    console.error('  export SHEETLINK_API_KEY=sl_...');
+    console.error('');
+
+    writeConfig({ api_key: options.apiKey, jwt: null });
+    console.log('API key saved to ~/.sheetlink/config.json');
+    console.log('');
+
+    // Verify it works
+    try {
+      const status = await getTierStatus();
+      if (status.subscription_tier !== 'max') {
+        console.error(`Warning: This key belongs to a ${status.subscription_tier} account. MAX tier is required for API key auth.`);
+        process.exit(1);
+      }
+      console.log(`Authenticated as ${status.email} (${status.subscription_tier} tier)`);
+    } catch (e) {
+      console.error(`Could not verify key: ${e.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --- OAuth / JWT path (PRO interactive) ---
+  console.log('Opening Google sign-in in your browser...');
+  console.log('');
+
+  const idToken = await googleOAuthFlow();
+  const jwt = await exchangeGoogleToken(idToken);
+
+  writeConfig({ jwt, api_key: null });
+  console.log('');
+  console.log('Authenticated. JWT saved to ~/.sheetlink/config.json');
+  console.log('Note: JWT expires in ~1 hour. Re-run `sheetlink auth` when needed.');
+  console.log('For unattended automation, upgrade to MAX and use `sheetlink auth --api-key sl_...`');
+}
+
+async function googleOAuthFlow() {
+  return new Promise((resolve, reject) => {
+    const state = randomBytes(16).toString('hex');
+    const nonce = randomBytes(16).toString('hex');
+
+    const params = new URLSearchParams({
+      client_id: GOOGLE_CLIENT_ID,
+      redirect_uri: REDIRECT_URI,
+      response_type: 'id_token',
+      scope: 'openid email profile',
+      state,
+      nonce,
+    });
+
+    const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
+
+    // Start local server to catch the redirect
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost:${REDIRECT_PORT}`);
+
+      // Google returns id_token in the fragment (#) which is client-side only.
+      // We serve a tiny page that POSTs it to our server.
+      if (url.pathname === '/callback') {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`<!DOCTYPE html>
+<html>
+<body>
+<script>
+  const params = new URLSearchParams(location.hash.slice(1));
+  fetch('/token', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify({ id_token: params.get('id_token'), state: params.get('state') })
+  }).then(() => {
+    document.body.innerHTML = '<p>Authenticated! You can close this tab.</p>';
+  });
+</script>
+</body>
+</html>`);
+        return;
+      }
+
+      if (url.pathname === '/token' && req.method === 'POST') {
+        let body = '';
+        req.on('data', d => body += d);
+        req.on('end', () => {
+          res.writeHead(200);
+          res.end('ok');
+          server.close();
+          try {
+            const { id_token, state: returnedState } = JSON.parse(body);
+            if (returnedState !== state) return reject(new Error('State mismatch — possible CSRF'));
+            resolve(id_token);
+          } catch (e) {
+            reject(e);
+          }
+        });
+        return;
+      }
+
+      res.writeHead(404);
+      res.end();
+    });
+
+    server.listen(REDIRECT_PORT, async () => {
+      try {
+        const { default: open } = await import('open');
+        await open(authUrl);
+      } catch {
+        console.log(`Open this URL in your browser:\n${authUrl}`);
+      }
+    });
+
+    server.on('error', reject);
+    setTimeout(() => { server.close(); reject(new Error('OAuth timeout (2 minutes)')); }, 120_000);
+  });
+}
+
+async function exchangeGoogleToken(idToken) {
+  const res = await fetch(`${getApiUrl()}/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id_token: idToken }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`Login failed: ${err.detail || res.statusText}`);
+  }
+
+  const data = await res.json();
+  return data.token;
+}

package/src/commands/config.js

@@ -0,0 +1,70 @@
+/**
+ * config.js - `sheetlink config`
+ *
+ * Show or update CLI configuration.
+ *
+ * Usage:
+ *   sheetlink config                       # Show current config
+ *   sheetlink config --set output=json     # Set default output
+ *   sheetlink config --set api_url=https://api.sheetlink.app
+ */
+
+import path from 'path';
+import os from 'os';
+import { readConfig, writeConfig } from '../config.js';
+
+const CONFIG_FILE = path.join(os.homedir(), '.sheetlink', 'config.json');
+
+const SETTABLE_KEYS = ['default_output', 'api_url'];
+
+export function cmdConfig(options) {
+  if (options.set) {
+    const eqIdx = options.set.indexOf('=');
+    if (eqIdx === -1) {
+      console.error('Usage: sheetlink config --set key=value');
+      process.exit(1);
+    }
+    const key = options.set.slice(0, eqIdx);
+    const value = options.set.slice(eqIdx + 1);
+
+    if (!SETTABLE_KEYS.includes(key)) {
+      console.error(`Unknown config key: ${key}`);
+      console.error(`Settable keys: ${SETTABLE_KEYS.join(', ')}`);
+      process.exit(1);
+    }
+
+    writeConfig({ [key]: value });
+    console.log(`Set ${key}=${value}`);
+    return;
+  }
+
+  // Show current config
+  const cfg = readConfig();
+
+  console.log(`\nConfig file: ${CONFIG_FILE}\n`);
+
+  if (!cfg || Object.keys(cfg).length === 0) {
+    console.log('No config set. Run `sheetlink auth` to get started.');
+    return;
+  }
+
+  const display = {
+    ...cfg,
+    api_key: cfg.api_key ? `${cfg.api_key.slice(0, 8)}...` : undefined,
+    jwt: cfg.jwt ? '<set>' : undefined,
+  };
+
+  for (const [k, v] of Object.entries(display)) {
+    if (v !== undefined) console.log(`  ${k}: ${v}`);
+  }
+
+  console.log('');
+
+  // Env var overrides
+  if (process.env.SHEETLINK_API_KEY) {
+    console.log('  SHEETLINK_API_KEY: <set via env var> (overrides config file)');
+  }
+  if (process.env.SHEETLINK_OUTPUT) {
+    console.log(`  SHEETLINK_OUTPUT: ${process.env.SHEETLINK_OUTPUT} (overrides config file)`);
+  }
+}

package/src/commands/items.js

@@ -0,0 +1,27 @@
+/**
+ * items.js - `sheetlink items`
+ *
+ * Lists all connected bank accounts for the authenticated user.
+ */
+
+import { listItems } from '../api.js';
+
+export async function cmdItems() {
+  const { items } = await listItems();
+
+  if (!items || items.length === 0) {
+    console.log('No connected banks. Connect one at https://sheetlink.app/dashboard');
+    return;
+  }
+
+  console.log(`\nConnected banks (${items.length}):\n`);
+  for (const item of items) {
+    const lastSync = item.last_synced_at
+      ? new Date(item.last_synced_at).toLocaleString()
+      : 'never';
+    console.log(`  ${item.institution_name || 'Unknown'}`);
+    console.log(`    item_id:      ${item.item_id}`);
+    console.log(`    last synced:  ${lastSync}`);
+    console.log('');
+  }
+}

package/src/commands/sync.js

@@ -0,0 +1,88 @@
+/**
+ * sync.js - `sheetlink sync`
+ *
+ * Fetches transactions from SheetLink API and routes to output adapter.
+ *
+ * Output modes:
+ *   json (default)            - JSON to stdout, pipeable
+ *   csv [--file path]         - Snapshot CSV, overwrites each run (PRO+)
+ *   postgres://...            - Upsert to Postgres (MAX only)
+ *   sqlite:///path/to/db      - Upsert to SQLite (MAX only)
+ */
+
+import { listItems, syncItem } from '../api.js';
+import { getDefaultOutput } from '../config.js';
+import { writeJson } from '../adapters/json.js';
+import { writeCsv } from '../adapters/csv.js';
+import { writePostgres } from '../adapters/postgres.js';
+import { writeSQLite } from '../adapters/sqlite.js';
+
+export async function cmdSync(options) {
+  const output = options.output || getDefaultOutput();
+  const itemId = options.item || null;
+
+  // Collect items to sync
+  let itemIds;
+  if (itemId) {
+    itemIds = [itemId];
+  } else {
+    const { items } = await listItems();
+    if (!items || items.length === 0) {
+      console.error('No connected banks found. Connect a bank at https://sheetlink.app/dashboard');
+      process.exit(1);
+    }
+    itemIds = items.map(i => i.item_id);
+  }
+
+  // Sync each item and collect results
+  const allTransactions = [];
+  const allAccounts = [];
+  const results = [];
+
+  for (const id of itemIds) {
+    process.stderr.write(`Syncing ${id}...`);
+    try {
+      const result = await syncItem(id);
+      allTransactions.push(...(result.transactions || []));
+      allAccounts.push(...(result.accounts || []));
+      results.push({ item_id: id, ...result });
+      process.stderr.write(` ${result.transactions?.length ?? 0} transactions\n`);
+    } catch (e) {
+      process.stderr.write(` error: ${e.message}\n`);
+    }
+  }
+
+  if (allTransactions.length === 0 && allAccounts.length === 0) {
+    console.error('No data returned from sync.');
+    process.exit(1);
+  }
+
+  const synced_at = new Date().toISOString();
+
+  // Route to output adapter
+  if (output === 'json') {
+    writeJson({ synced_at, items: results });
+    return;
+  }
+
+  if (output === 'csv') {
+    writeCsv(allTransactions, options.file);
+    return;
+  }
+
+  if (output.startsWith('postgres://') || output.startsWith('postgresql://')) {
+    await writePostgres(allTransactions, allAccounts, output);
+    return;
+  }
+
+  if (output.startsWith('sqlite://')) {
+    // sqlite:///absolute/path or sqlite://relative/path
+    const dbPath = output.replace(/^sqlite:\/\/\/?/, '') || './sheetlink.db';
+    writeSQLite(allTransactions, allAccounts, dbPath);
+    return;
+  }
+
+  console.error(`Unknown output: ${output}`);
+  console.error('Valid options: json, csv, postgres://..., sqlite:///path/to/db');
+  process.exit(1);
+}

package/src/config.js

@@ -0,0 +1,78 @@
+/**
+ * config.js - Read/write ~/.sheetlink/config.json
+ *
+ * Config file stores:
+ *   api_key        - SheetLink API key (sl_...) for MAX tier unattended auth
+ *   jwt            - JWT token for PRO tier interactive auth
+ *   default_output - Default output mode (json, csv, postgres://..., sqlite://...)
+ *   api_url        - Backend URL (default: https://api.sheetlink.app)
+ *
+ * Priority for API key: SHEETLINK_API_KEY env var > config file
+ * Priority for JWT: config file only (set by `sheetlink auth`)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const CONFIG_DIR = path.join(os.homedir(), '.sheetlink');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const DEFAULT_API_URL = 'https://api.sheetlink.app';
+
+export function readConfig() {
+  try {
+    if (!fs.existsSync(CONFIG_FILE)) return {};
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(updates) {
+  const current = readConfig();
+  const next = { ...current, ...updates };
+
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { mode: 0o700 });
+  } else {
+    // Enforce correct permissions even if dir already exists
+    fs.chmodSync(CONFIG_DIR, 0o700);
+  }
+
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), { mode: 0o600 });
+  // Enforce file permissions after write (some systems ignore mode on writeFileSync)
+  fs.chmodSync(CONFIG_FILE, 0o600);
+  return next;
+}
+
+export function getApiKey() {
+  // Env var takes precedence
+  if (process.env.SHEETLINK_API_KEY) return process.env.SHEETLINK_API_KEY;
+  return readConfig().api_key || null;
+}
+
+export function getJwt() {
+  return readConfig().jwt || null;
+}
+
+export function getApiUrl() {
+  return process.env.SHEETLINK_API_URL || readConfig().api_url || DEFAULT_API_URL;
+}
+
+export function getDefaultOutput() {
+  return process.env.SHEETLINK_OUTPUT || readConfig().default_output || 'json';
+}
+
+/**
+ * Returns the best available auth header value, or null if not configured.
+ * API key takes priority over JWT (API key = MAX unattended, JWT = PRO interactive).
+ */
+export function getAuthHeader() {
+  const apiKey = getApiKey();
+  if (apiKey) return `Bearer ${apiKey}`;
+
+  const jwt = getJwt();
+  if (jwt) return `Bearer ${jwt}`;
+
+  return null;
+}

package/src/index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * SheetLink CLI
+ *
+ * Sync your bank transactions to any destination — JSON, CSV, Postgres, SQLite.
+ *
+ * PRO tier:  interactive auth (JWT), manual runs
+ * MAX tier:  API key auth, unattended/cron automation
+ *
+ * https://sheetlink.app
+ */
+
+import { program } from 'commander';
+import { createRequire } from 'module';
+import { cmdAuth } from './commands/auth.js';
+import { cmdSync } from './commands/sync.js';
+import { cmdItems } from './commands/items.js';
+import { cmdConfig } from './commands/config.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+program
+  .name('sheetlink')
+  .description('Sync bank transactions from SheetLink to any destination')
+  .version(pkg.version);
+
+// ── auth ────────────────────────────────────────────────────────────────────
+
+program
+  .command('auth')
+  .description('Authenticate with SheetLink (OAuth for PRO, API key for MAX)')
+  .option('--api-key <key>', 'Set a MAX tier API key (sl_...) for unattended automation')
+  .action(cmdAuth);
+
+// ── sync ────────────────────────────────────────────────────────────────────
+
+program
+  .command('sync')
+  .description('Sync bank transactions and output to chosen destination')
+  .option('--output <dest>', 'Output destination: json (default), csv, postgres://..., sqlite:///path')
+  .option('--file <path>', 'File path for CSV output (default: ./sheetlink-transactions.csv)')
+  .option('--item <item_id>', 'Sync a specific item only (default: all connected banks)')
+  .addHelpText('after', `
+Examples:
+  sheetlink sync                                         JSON to stdout (pipeable)
+  sheetlink sync | jq '.items[].transactions | length'  Count transactions
+  sheetlink sync --output csv                            Snapshot CSV (overwrites each run)
+  sheetlink sync --output csv --file ~/finances.csv      CSV to custom path
+  sheetlink sync --output postgres://localhost/mydb      Upsert to Postgres (MAX only)
+  sheetlink sync --output sqlite:///~/finance.db         Upsert to SQLite (MAX only)
+  sheetlink sync --item VBX93wmRY4Iy...                  Sync one bank only
+  `)
+  .action(cmdSync);
+
+// ── items ───────────────────────────────────────────────────────────────────
+
+program
+  .command('items')
+  .description('List connected bank accounts')
+  .action(cmdItems);
+
+// ── config ──────────────────────────────────────────────────────────────────
+
+program
+  .command('config')
+  .description('Show or update CLI configuration')
+  .option('--set <key=value>', 'Set a config value (e.g. --set default_output=csv)')
+  .addHelpText('after', `
+Settable keys:
+  default_output   Default output destination (json, csv, postgres://..., sqlite://...)
+  api_url          Backend API URL (default: https://api.sheetlink.app)
+
+Environment variable overrides:
+  SHEETLINK_API_KEY   API key (overrides config file)
+  SHEETLINK_OUTPUT    Default output (overrides config file)
+  SHEETLINK_API_URL   Backend URL (overrides config file)
+  `)
+  .action(cmdConfig);
+
+program.parse();