@finopsbricks/fob-txn

Command-line client and importable library for the FinOpsBricks Transactions API — a 2-in-1, the same shape as @finopsbricks/fob-stm. The txn app polls a mailbox over IMAP, extracts one transaction per bank notification email, and exposes accounts + transactions through a key-authenticated API. This package is how workers and the terminal read that data.

npm install -g @finopsbricks/fob-txn

Getting started

1. Create an API key for your org at https://txn.finopsbricks.com/orgs/<your-org>/settings/apikeys.

2. Add a profile:

   fob-txn config profiles add myorg --api-key fob_txn_xxxx --api-secret yyyy

   --api-url is optional and defaults to https://txn.finopsbricks.com.

3. Confirm: fob-txn whoami

fob-txn getting-started prints these steps in-band (and says so when a profile already exists).

Usage

fob-txn <resource> <action> [target] [options]

fob-txn config profiles list
fob-txn config profiles use myorg
fob-txn --profile other accounts list         # one-off override

fob-txn accounts list [--status active] [--all] [--json|--format csv] [--fields id,name]
fob-txn accounts show <id>

fob-txn transactions list --from 2026-08-01 --to 2026-08-31
fob-txn transactions list --account <id> --all --json
fob-txn transactions list --acc-no 0006
fob-txn transactions list --updated-from 2026-09-03T04:00:00Z --sort-by updated_at --sort-order ASC
fob-txn transactions list --updated-from 2026-09-01     # a bare date = that whole day, in your local zone

--from/--to bound the transaction date (YYYY-MM-DD). --created-from/--created-to and --updated-from/--updated-to bound the row's timestamps: pass an ISO 8601 instant to send it as-is, or a bare YYYY-MM-DD and the CLI widens it to that whole day in your local timezone before sending (the server itself only accepts instants there). --sort-by date|created_at|updated_at and --sort-order ASC|DESC control ordering; updated_at moves whenever a row changes (a comment edit, an account re-link), which is what makes --updated-from + --sort-by updated_at a watermark walk.

Every list command supports --page/--limit (one page, default 100), --all (every page, capped at 15,000 rows), --json, --format csv, --output <file>.

Amounts

The API stores inflow / outflow / balance as integers scaled ×1000 from the major unit (₹1,234.50 → 1234500). The table view divides them back to decimals; --json returns the raw integers exactly as the API does, so scripts never have to guess the scale.

As a library

import { fobTxn } from '@finopsbricks/fob-txn';

const txn = fobTxn({ api_key: 'fob_txn_…', api_secret: '…' }); // api_url optional

const accounts = await txn.accounts.getAll();                       // Account[]
const rows = await txn.transactions.getAll({ date_from: '2026-08-01' }); // Transaction[], newest first
const edits = await txn.transactions.getAll({                            // everything changed since a watermark
  updated_at_from: '2026-09-03T04:00:00Z', sort_by: 'updated_at', sort_order: 'ASC',
});
const { data, page_context } = await txn.transactions.list({ account: 'abc', page: 1, limit: 100 });
const me = await txn.whoami();                                      // { org_id, org_name, api_key_name, scopes }

The library never reads process.env — inject credentials explicitly. Errors are ApiError instances with code (UNAUTHORIZED, FORBIDDEN, NOT_FOUND, HTTP_ERROR, NO_CREDENTIALS, …) and status.

Config

Profiles live in ~/.fob/fob-txn/config.yml (mode 0600). Override the directory with FOB_TXN_CONFIG_DIR. FOB_DEBUG=1 prints stack traces on error.