@iovdin/bunk 1.0.1

package/README.md

@@ -0,0 +1,153 @@
+# bunk — bunq CLI
+
+A command-line tool to authenticate with [bunq](https://www.bunq.com) via OAuth2, download all your events and index payments locally into SQLite for fast offline querying.
+
+## Installation
+
+```bash
+npm install -g bunk
+```
+
+Or for local dev:
+
+```bash
+npm i
+npm link   # makes `bunk` available on your PATH
+```
+
+> **Requires Node.js >= 22** — uses the built-in `node:sqlite` module.
+
+## Configuration
+
+Config is stored at `~/.config/bunk/config.json` and is managed automatically by `bunk auth`.
+
+```json
+{
+  "clientId": "...",
+  "clientSecret": "...",
+  "accessToken": "...",
+  "installationToken": "...",
+  "sessionToken": "...",
+  "userId": 12345678,
+  "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
+  "privateKey": "-----BEGIN PRIVATE KEY-----\n..."
+}
+```
+
+## Usage
+
+### 1. Authenticate
+
+```bash
+bunk auth
+# or specify a custom callback port/host
+bunk auth --port 4589 --host 127.0.0.1
+```
+
+This will:
+1. Prompt you for your **OAuth2 `client_id` and `client_secret`** (from [bunq Developer settings](https://www.bunq.com/developer))
+2. Open the bunq authorization URL in your browser
+3. Start a local HTTP server to capture the OAuth2 callback
+4. Exchange the code for an `access_token`
+5. Register an RSA key pair, an installation and a device-server with the bunq API
+6. Create a session and save `sessionToken` + `userId` to config
+
+All credentials are persisted to `~/.config/bunk/config.json` (mode `0600`) so subsequent runs skip steps already completed.
+
+---
+
+### 2. Fetch events
+
+```bash
+bunk fetch
+# or specify a custom database path
+bunk fetch --output ~/bunq/index.sqlite
+# verbose output
+bunk fetch --verbose
+# wipe database and re-fetch everything
+bunk fetch --clean
+```
+
+Downloads all bunq events (payments, card actions, etc.) from the API and stores the raw JSON in a local SQLite database.
+
+- On the **first run** (empty database) it performs a full backfill, paginating back in time until there are no more events.
+- On **subsequent runs** it only fetches events newer than the highest `id` already stored.
+
+Events are stored in the `events` table:
+
+```sql
+CREATE TABLE events (
+  id      INTEGER PRIMARY KEY,
+  content TEXT NOT NULL        -- raw bunq event JSON
+);
+```
+
+---
+
+### 3. Index payments
+
+```bash
+bunk index
+# or specify a custom database path
+bunk index --output ~/bunq/index.sqlite
+```
+
+Extracts structured payment data from the raw `events` table into a `payments` table for easy querying. Supports both **Payment** and **MasterCardAction** event types.
+
+```sql
+CREATE TABLE payments (
+  event_id          INTEGER PRIMARY KEY,
+  created_at        TEXT,
+  account_id        TEXT,
+  amount_value      REAL,      -- negative for card payments / debits
+  amount_currency   TEXT,
+  status            TEXT,
+  description       TEXT,
+  counterparty_name TEXT,
+  counterparty_iban TEXT,
+  my_name           TEXT,
+  my_iban           TEXT
+);
+```
+
+---
+
+## Example queries
+
+```sql
+-- Last 20 transactions
+SELECT event_id, created_at, amount_value, amount_currency, counterparty_name, description
+FROM payments
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- Total spent per counterparty (debits only)
+SELECT counterparty_name, ROUND(SUM(amount_value), 2) AS total
+FROM payments
+WHERE amount_value < 0
+GROUP BY counterparty_name
+ORDER BY total ASC
+LIMIT 20;
+
+-- All card payments this month
+SELECT created_at, amount_value, description, counterparty_name
+FROM payments
+WHERE status != 'COMPLETED'   -- MasterCardAction statuses differ
+  AND created_at >= date('now', 'start of month')
+ORDER BY created_at DESC;
+```
+
+---
+
+## crontab
+
+To keep your local database up to date automatically, add the following to your crontab (`crontab -e`).  
+Adjust the Node.js path to match your environment (`node --version` to check):
+
+```crontab
+HOME=/Users/your_username
+PATH=/Users/your_username/.nvm/versions/node/v22.20.0/bin:/usr/local/bin:/usr/bin:/bin
+
+# Fetch new bunq events and index payments every 15 minutes
+*/15 * * * * bunk fetch && bunk index >> $HOME/bunk.log 2>&1
+```

package/bin/bunk.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const { auth } = require('../lib/auth');
+const { fetchEvents } = require('../lib/fetch');
+const { indexPayments } = require('../lib/index');
+
+const program = new Command();
+
+program
+  .name('bunk')
+  .description('bunq OAuth2 helper CLI')
+  .version('0.0.1');
+
+program
+  .command('auth')
+  .description('Authenticate with bunq using OAuth2 and store tokens in ~/.config/bunk/config.txt')
+  .option('-p, --port <port>', 'Local callback server port', (v) => parseInt(v, 10), 4589)
+  .option('--host <host>', 'Local callback server host', '127.0.0.1')
+  .action(async (opts) => {
+    await auth(opts);
+  });
+
+program
+  .command('fetch')
+  .description('Download all bunq events and store in SQLite database')
+  .option('-o, --output <path>', 'Output SQLite database path', '~/bunq/index.sqlite')
+  .option('-v, --verbose', 'Show detailed progress', false)
+  .option('--clean', 'Remove existing database and re-fetch everything', false)
+  .action(async (opts) => {
+    await fetchEvents(opts);
+  });
+
+program
+  .command('index')
+  .description('Index latest events into payments table')
+  .option('-o, --output <path>', 'Output SQLite database path', '~/bunq/index.sqlite')
+  .action(async (opts) => {
+    await indexPayments(opts);
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/lib/auth.js

@@ -0,0 +1,413 @@
+const http = require('http');
+const { URL } = require('url');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require("crypto");
+
+const environment = 'production'
+
+const domains = {
+  sandbox: { 
+    oauthApi: "api-oauth.sandbox.bunq.com",
+    oauth: "oauth.sandbox.bunq.com",
+    api: "public-api.sandbox.bunq.com"
+  },
+  production: {
+    oauthApi: "api.oauth.bunq.com",
+    oauth: "oauth.bunq.com",
+    api: "api.bunq.com"
+  }
+}
+
+
+function configDir() {
+  return path.join(os.homedir(), '.config', 'bunk');
+}
+
+function configPath() {
+  return path.join(configDir(), 'config.json');
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+// config is stored as JSON; parsing/serialization is done inline in readExistingConfig/writeConfig
+
+function readExistingConfig() {
+  try {
+    const text = fs.readFileSync(configPath(), 'utf8');
+    const trimmed = String(text || '').trim();
+    if (!trimmed) return {};
+    const obj = JSON.parse(trimmed);
+    return obj && typeof obj === 'object' ? obj : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(obj) {
+  ensureDir(configDir());
+  const text = JSON.stringify(obj || {}, null, 2) + '\n';
+  fs.writeFileSync(configPath(), text, { mode: 0o600 });
+}
+
+function question(prompt) {
+  return new Promise((resolve) => {
+    process.stdout.write(prompt);
+    let buf = '';
+    const onData = (chunk) => {
+      buf += chunk.toString('utf8');
+      const idx = buf.indexOf('\n');
+      if (idx >= 0) {
+        process.stdin.off('data', onData);
+        resolve(buf.slice(0, idx).trim());
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+async function exchangeToken({
+  grantType,
+  code,
+  redirectUri,
+  clientId,
+  clientSecret,
+}) {
+  const u = new URL(`https://${domains[environment].oauthApi}/v1/token`);
+
+  u.searchParams.set('grant_type', grantType);
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('client_id', clientId);
+  u.searchParams.set('client_secret', clientSecret);
+  if (code) u.searchParams.set('code', code);
+
+  // bunq's OAuth token endpoint uses query parameters
+  const res = await fetch(u.toString(), { method: 'POST' });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`bunq token endpoint error (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+
+
+function generateBunqKeyPair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    publicKeyEncoding: {
+      type: "spki",       // ✅ required for bunq
+      format: "pem"
+    },
+    privateKeyEncoding: {
+      type: "pkcs8",      // ✅ required for bunq
+      format: "pem"
+    }
+  });
+
+  return {
+    publicKey,
+    privateKey
+  };
+}
+
+function signBody(body, privateKey) {
+  const signer = crypto.createSign("RSA-SHA256");
+  signer.update(body);
+  signer.end();
+  return signer.sign(privateKey, "base64");
+}
+
+/*
+async function createSession({ access_token }) {
+  const res = await fetch(`https://${domains[environment].api}/v1/session-server`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Bunq-Client-Authentication': access_token,
+      'X-Bunq-Language': 'en_US',
+      'X-Bunq-Region': 'nl_NL',
+      'X-Bunq-Client-Request-Id': Date.now().toString(),
+      'Cache-Control': 'no-cache'
+      // Authorization: `Bearer ${access_token}`,
+      // Accept: 'application/json',
+      // 'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({}),
+  });
+
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    json = { raw: text };
+  }
+
+  if (!res.ok) {
+    throw new Error(
+      `bunq session-server error (${res.status}): ${typeof text === 'string' ? text : JSON.stringify(json)}`,
+    );
+  }
+
+  const sessionToken = res.headers.get('x-bunq-client-authentication');
+  if (!sessionToken) {
+    throw new Error(
+      `Missing x-bunq-client-authentication header from session-server response. Body: ${text}`,
+    );
+  }
+
+  // Try to find user id in response payload.
+  // bunq responses are typically arrays of objects like {UserPerson:{...}} wrapped in Response.
+  let userId;
+  try {
+    const responses = Array.isArray(json.Response) ? json.Response : [];
+    for (const item of responses) {
+      if (!item || typeof item !== 'object') continue;
+      const v = item.UserPerson || item.UserCompany || item.UserLight || item.UserApiKey;
+      if (v && v.id) {
+        userId = v.id;
+        break;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return { sessionToken, session: json, userId };
+}
+*/
+
+async function auth({ host = '127.0.0.1', port = 4589 }) {
+  const redirectUri = `http://${host}:${port}/callback`;
+
+  const existing = readExistingConfig();
+  let { 
+    clientId, clientSecret, 
+    accessToken, 
+    publicKey, privateKey, 
+    installationToken,
+    sessionToken,
+    userId
+  } = existing;
+
+  if (!publicKey || !privateKey) {
+    const res = generateBunqKeyPair()
+    writeConfig({ ...existing, ...res });
+
+  }
+  if (!clientId || !clientSecret) {
+    console.log(`\nThis command will start a local HTTP server to capture bunq OAuth redirect.`);
+    console.log(`1) In bunq Developer settings create an OAuth app (or edit existing).`);
+    console.log(`2) Set Redirect URL to: ${redirectUri}`);
+    console.log(`\nThen paste the OAuth credentials here (they will be stored in ${configPath()}):\n`);
+
+    clientId = clientId || (await question(`client_id: `));
+    clientSecret = clientSecret || (await question(`client_secret: `));
+
+    if (!clientId || !clientSecret) {
+      throw new Error('client_id and client_secret are required');
+    }
+
+    // Save immediately
+    writeConfig({ ...readExistingConfig(), clientId, clientSecret, redirectUri });
+  }
+
+  if (!accessToken) {
+    // bunq OAuth base (common)
+    const authUrl = new URL(`https://${domains[environment].oauth}/auth`);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('client_id', clientId);
+    authUrl.searchParams.set('redirect_uri', redirectUri);
+    // Keep scope optional; bunq may allow empty or require specific.
+    if (existing.scope) authUrl.searchParams.set('scope', existing.scope);
+
+    const finalAuthUrl = authUrl.toString();
+    console.log(`\nAuthorization URL (open in your browser):\n${finalAuthUrl}\n`);
+
+    // On macOS automatically open the browser.
+    if (process.platform === 'darwin') {
+      try {
+        const { spawn } = require('child_process');
+        spawn('open', [finalAuthUrl], { stdio: 'ignore', detached: true }).unref();
+      } catch {
+        // ignore
+      }
+    }
+
+    console.log('Waiting for you to authorize in bunq...');
+
+    const code = await new Promise((resolve, reject) => {
+      const server = http.createServer(async (req, res) => {
+        try {
+          const u = new URL(req.url, `http://${host}:${port}`);
+          if (u.pathname !== '/callback') {
+            res.writeHead(404, { 'content-type': 'text/plain' });
+            res.end('Not found');
+            return;
+          }
+
+          const err = u.searchParams.get('error');
+          if (err) {
+            const desc = u.searchParams.get('error_description') || '';
+            res.writeHead(400, { 'content-type': 'text/plain' });
+            res.end(`OAuth error: ${err} ${desc}`);
+            server.close();
+            reject(new Error(`OAuth error: ${err} ${desc}`));
+            return;
+          }
+
+          const code = u.searchParams.get('code');
+          if (!code) {
+            res.writeHead(400, { 'content-type': 'text/plain' });
+            res.end('Missing ?code=');
+            return;
+          }
+
+          const html = `You can return to the terminal`;
+          res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+          res.end(html);
+          server.close();
+          resolve(code);
+        } catch (e) {
+          reject(e);
+        }
+      });
+
+      server.on('error', reject);
+      server.listen(port, host, () => {
+        // listening
+      });
+    });
+
+    console.log('Received authorization code, exchanging for tokens...');
+
+    const tokenRes = await exchangeToken({
+      grantType: 'authorization_code',
+      code,
+      redirectUri,
+      clientId,
+      clientSecret,
+    });
+
+    const { access_token } = tokenRes;
+    if (!access_token) {
+      throw new Error(`Token response missing access_token:\n${JSON.stringify(tokenRes)}`);
+    }
+
+    accessToken = access_token
+    writeConfig({
+      ...readExistingConfig(),
+      accessToken: access_token
+    });
+  }
+
+  if (!installationToken) {
+    console.log('Creating bunq installation token...');
+
+    let res = await fetch(
+      `https://${domains[environment].api}/v1/installation`,
+      {
+        method: "POST",
+        headers: {
+          "Cache-Control": "no-cache",
+          "User-Agent": "bunk-app",
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          client_public_key: publicKey
+        })
+      }
+    );
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`bunq installation token error (${res.status}): ${text}`);
+    }
+    res = await res.json();
+    console.log(JSON.stringify(res, null, "  "))
+    installationToken = res.Response[1].Token.token;
+
+
+    writeConfig({
+      ...readExistingConfig(),
+      installationToken
+    });
+    console.log('Registering bunq device');
+
+    const body = JSON.stringify({
+      description: "bunk server",
+      secret: accessToken
+    });
+
+    res = await fetch(
+      `https://${domains[environment].api}/v1/device-server`, {
+        method: "POST",
+        body,
+        headers: {
+          "Cache-Control": "no-cache",
+          "User-Agent": "bunk-app",
+          "Content-Type": "application/json",
+          "X-Bunq-Client-Authentication": installationToken,
+          "X-Bunq-Client-Signature": signBody(body, privateKey)
+        }
+      });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`bunq device registration error (${res.status}): ${text}`);
+    }
+  }
+
+  if (!sessionToken || !userId) {
+    console.log('Creating bunq API session ...');
+
+    const body = JSON.stringify({
+      secret: accessToken
+    });
+    let res = await fetch(
+      `https://${domains[environment].api}/v1/session-server`, {
+        method: "POST",
+        body,
+        headers: {
+          "Cache-Control": "no-cache",
+          "User-Agent": "bunk-app",
+          "Content-Type": "application/json",
+          "X-Bunq-Client-Authentication": installationToken,
+          "X-Bunq-Client-Signature": signBody(body, privateKey)
+        }
+      });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`bunq device registration error (${res.status}): ${text}`);
+    }
+    res = await res.json()
+    console.log(JSON.stringify(res, null, "  "))
+
+    const response = res?.Response ?? [];
+
+    sessionToken =
+      response.find(x => x?.Token?.token != null)?.Token?.token ?? null;
+
+    userId =
+      response.find(x => x?.UserPerson?.id != null)?.UserPerson?.id ??
+        response.find(x => x?.UserApiKey?.id != null)?.UserApiKey?.id ??
+        null;
+
+    writeConfig({
+      ...readExistingConfig(),
+      sessionToken,
+      userId
+    });
+
+  }
+
+
+  console.log(`\nSaved tokens + session to ${configPath()}`);
+}
+
+module.exports = { auth, configPath };

package/lib/fetch.js

@@ -0,0 +1,232 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Node.js v25+ built-in SQLite
+const sqlite = require('node:sqlite');
+
+const { configPath } = require('./auth');
+
+const environment = 'production';
+const domains = {
+  sandbox: {
+    oauthApi: 'api-oauth.sandbox.bunq.com',
+    oauth: 'oauth.sandbox.bunq.com',
+    api: 'public-api.sandbox.bunq.com',
+  },
+  production: {
+    oauthApi: 'api.oauth.bunq.com',
+    oauth: 'oauth.bunq.com',
+    api: 'api.bunq.com',
+  },
+};
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function readExistingConfig() {
+  try {
+    const text = fs.readFileSync(configPath(), 'utf8');
+    const trimmed = String(text || '').trim();
+    if (!trimmed) return {};
+    const obj = JSON.parse(trimmed);
+    return obj && typeof obj === 'object' ? obj : {};
+  } catch {
+    return {};
+  }
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function resolveDbPath(opts, config) {
+  const fromOpts = opts && opts.output;
+  const fromConfig = config && config.output;
+  const p = expandHome(fromOpts || fromConfig || '~/bunq/index.sqlite');
+  return p;
+}
+
+function getDb(dbPath) {
+  ensureDir(path.dirname(dbPath));
+  const db = new sqlite.DatabaseSync(dbPath);
+  // Improve concurrency a bit and speed inserts
+  db.exec('PRAGMA journal_mode = WAL;');
+  db.exec('PRAGMA synchronous = NORMAL;');
+  return db;
+}
+
+function ensureSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY,
+      content TEXT NOT NULL
+    );
+  `);
+}
+
+function getMaxId(db) {
+  const row = db.prepare('SELECT MAX(id) AS max_id FROM events').get();
+  return row && row.max_id ? Number(row.max_id) : 0;
+}
+
+function deleteDbFiles(dbPath) {
+  for (const p of [dbPath, dbPath + '-wal', dbPath + '-shm']) {
+    try {
+      fs.unlinkSync(p);
+    } catch {}
+  }
+}
+
+async function bunqGetJson(urlPath, { sessionToken } = {}) {
+  const url = urlPath.startsWith('http')
+    ? urlPath
+    : `https://${domains[environment].api}${urlPath}`;
+
+  const res = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'X-Bunq-Client-Authentication': sessionToken,
+      'Content-Type': 'application/json',
+      'User-Agent': 'bunk-cli/1.0',
+      'X-Bunq-Language': 'en_US',
+      'X-Bunq-Region': 'en_US',
+      'X-Bunq-Geolocation': '0 0 0 0 NL',
+    },
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`bunq GET ${urlPath} failed (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+
+function extractEvents(payload) {
+  const out = [];
+  const arr = Array.isArray(payload?.Response) ? payload.Response : [];
+  for (const item of arr) {
+    const ev = item?.Event;
+    if (ev && ev.id != null) out.push(ev);
+  }
+  return out;
+}
+
+async function fetchEvents(opts = {}) {
+  const verbose = !!opts.verbose;
+  const clean = !!opts.clean;
+
+  const cfg = readExistingConfig();
+  const sessionToken = cfg.sessionToken;
+  const userId = cfg.userId;
+
+  if (!sessionToken) {
+    throw new Error(`Missing sessionToken in ${configPath()}. Run: bunk auth`);
+  }
+  if (!userId) {
+    throw new Error(`Missing userId in ${configPath()}. Run: bunk auth`);
+  }
+
+  const dbPath = resolveDbPath(opts, cfg);
+
+  if (clean) {
+    if (verbose) console.log(`--clean: removing ${dbPath} (and -wal/-shm)`);
+    deleteDbFiles(dbPath);
+  }
+
+  const db = getDb(dbPath);
+  try {
+    ensureSchema(db);
+
+    const maxId = getMaxId(db);
+    const isEmpty = maxId === 0;
+
+    // per your comment: if collection is empty behave like --all
+    const modeAll = isEmpty;
+
+    // Insert/upsert (node:sqlite does not provide db.transaction like better-sqlite3)
+    const ins = db.prepare('INSERT OR REPLACE INTO events (id, content) VALUES (?, ?)');
+    const insertMany = (events) => {
+      db.exec('BEGIN');
+      try {
+        for (const ev of events) {
+          ins.run(Number(ev.id), JSON.stringify(ev));
+        }
+        db.exec('COMMIT');
+      } catch (e) {
+        try {
+          db.exec('ROLLBACK');
+        } catch {}
+        throw e;
+      }
+    };
+
+    const count = 200;
+
+    let nextPath;
+    if (modeAll) {
+      nextPath = `/v1/user/${userId}/event?count=${count}`;
+      console.log(`Database: ${dbPath}`);
+      console.log(`events table empty -> full backfill mode (count=${count})`);
+    } else {
+      // Only fetch newer than current max id
+      nextPath = `/v1/user/${userId}/event?count=${count}&newer_id=${encodeURIComponent(String(maxId))}`;
+      console.log(`Database: ${dbPath}`);
+      console.log(`Fetching newer events since id=${maxId} (count=${count})`);
+    }
+
+    let pages = 0;
+    let inserted = 0;
+
+    let lastPath = null;
+    while (nextPath) {
+      // Detect non-advancing pagination
+      if (nextPath === lastPath) {
+        if (verbose) console.warn(`Pagination did not advance (stuck on ${nextPath}). Stopping.`);
+        break;
+      }
+      lastPath = nextPath;
+
+      pages++;
+      if (verbose) console.log(`GET ${nextPath}`);
+      const json = await bunqGetJson(nextPath, { sessionToken });
+
+      const events = extractEvents(json);
+      if (events.length) {
+        insertMany(events);
+        inserted += events.length;
+      }
+
+      const pag = json?.Pagination || {};
+      if (modeAll) {
+        // walk back in time until older_url is null
+        nextPath = pag.older_url || null;
+      } else {
+        // When using newer_id, bunq may keep returning future_url=null.
+        // In that case, stop after the first page.
+        nextPath = pag.future_url || null;
+        if (!nextPath) {
+          break;
+        }
+      }
+
+      if (!verbose) {
+        process.stdout.write(`\rpages=${pages} inserted=${inserted}`);
+      }
+
+      // Safety: prevent infinite loops if API misbehaves
+      if (pages > 1_000_000) throw new Error('too many pages; aborting');
+    }
+
+    if (!verbose) process.stdout.write('\n');
+    console.log(`Done. pages=${pages}, inserted=${inserted}, maxId(now)=${getMaxId(db)}`);
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { fetchEvents };

package/lib/index.js

@@ -0,0 +1,116 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const sqlite = require('node:sqlite');
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function getDb(dbPath) {
+  ensureDir(path.dirname(dbPath));
+  const db = new sqlite.DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL;');
+  db.exec('PRAGMA synchronous = NORMAL;');
+  return db;
+}
+
+function ensurePaymentsSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS payments (
+      event_id INTEGER PRIMARY KEY,
+      created_at TEXT,
+      account_id TEXT,
+      amount_value REAL,
+      amount_currency TEXT,
+      status TEXT,
+      description TEXT,
+      counterparty_name TEXT,
+      counterparty_iban TEXT,
+      my_name TEXT,
+      my_iban TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_payments_created_at ON payments(created_at);
+    CREATE INDEX IF NOT EXISTS idx_payments_status ON payments(status);
+    CREATE INDEX IF NOT EXISTS idx_payments_counterparty_name ON payments(counterparty_name);
+  `);
+}
+
+function indexPayments(opts = {}) {
+  const dbPath = expandHome(opts.output || '~/bunq/index.sqlite');
+  const db = getDb(dbPath);
+
+  try {
+    ensurePaymentsSchema(db);
+
+    const row = db.prepare('SELECT COALESCE(MAX(event_id), 0) AS max_event_id FROM payments').get();
+    const maxEventId = Number(row?.max_event_id || 0);
+
+    const sql = `
+      INSERT OR IGNORE INTO payments (
+        event_id,
+        created_at,
+        account_id,
+        amount_value,
+        amount_currency,
+        status,
+        description,
+        counterparty_name,
+        counterparty_iban,
+        my_name,
+        my_iban
+      )
+      SELECT
+        json_extract(content, '$.id') AS event_id,
+        json_extract(content, '$.created') AS created_at,
+        json_extract(content, '$.monetary_account_id') AS account_id,
+        CAST(json_extract(content, '$.object.Payment.amount.value') AS REAL) AS amount_value,
+        json_extract(content, '$.object.Payment.amount.currency') AS amount_currency,
+        json_extract(content, '$.status') AS status,
+        json_extract(content, '$.object.Payment.description') AS description,
+        json_extract(content, '$.object.Payment.counterparty_alias.display_name') AS counterparty_name,
+        json_extract(content, '$.object.Payment.counterparty_alias.iban') AS counterparty_iban,
+        json_extract(content, '$.object.Payment.alias.display_name') AS my_name,
+        json_extract(content, '$.object.Payment.alias.iban') AS my_iban
+      FROM events
+      WHERE json_type(content, '$.object.Payment') = 'object'
+        AND CAST(json_extract(content, '$.id') AS INTEGER) > ?
+
+      UNION ALL
+
+      SELECT
+        json_extract(content, '$.id') AS event_id,
+        json_extract(content, '$.created') AS created_at,
+        json_extract(content, '$.monetary_account_id') AS account_id,
+        -ABS(CAST(json_extract(content, '$.object.MasterCardAction.amount_local.value') AS REAL)) AS amount_value,
+        json_extract(content, '$.object.MasterCardAction.amount_local.currency') AS amount_currency,
+        json_extract(content, '$.object.MasterCardAction.payment_status') AS status,
+        json_extract(content, '$.object.MasterCardAction.description') AS description,
+        json_extract(content, '$.object.MasterCardAction.counterparty_alias.display_name') AS counterparty_name,
+        json_extract(content, '$.object.MasterCardAction.counterparty_alias.iban') AS counterparty_iban,
+        json_extract(content, '$.object.MasterCardAction.alias.display_name') AS my_name,
+        json_extract(content, '$.object.MasterCardAction.alias.iban') AS my_iban
+      FROM events
+      WHERE json_type(content, '$.object.MasterCardAction') = 'object'
+        AND CAST(json_extract(content, '$.id') AS INTEGER) > ?
+    `;
+
+    const before = db.prepare('SELECT COUNT(*) AS n FROM payments').get().n;
+    db.prepare(sql).run(maxEventId, maxEventId);
+    const after = db.prepare('SELECT COUNT(*) AS n FROM payments').get().n;
+
+    console.log(`Indexed payments: +${after - before} (total=${after}) from events newer than event_id=${maxEventId}`);
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { indexPayments };

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@iovdin/bunk",
+  "version": "1.0.1",
+  "homepage": "https://github.com/iovdin/bunk#readme",
+  "description": "bunq CLI download and index transactions into sqlite database",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iovdin/bunk.git"
+  },
+  "bin": {
+    "bunk": "bin/bunk.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "start": "node bin/bunk.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "author": "Ilya Ovdin <iovdin@gmail.com>",
+  "license": "MIT"
+}