nbb-client


A robust, type-safe Node.js client for the National Bank of Belgium (NBB) CBSO API.

It simplifies fetching financial data, parses complex XBRL deposits into usable JSON, and automatically calculates key financial ratios (ROE, Liquidity, Solvency, etc.) with multilingual labels (EN, FR, NL).

Features

* 🚀 Easy API: Simple getFinancials(enterpriseNumber) method.
* 📊 Automatic Ratios: Calculates Net Profit Margin, Current Ratio, Debt-to-Equity, and more.
* 🌍 Multilingual: Full support for English, French, and Dutch labels.
* ⚡ Built-in Caching: File-system caching to avoid redundant API calls and rate limits.
* 📅 Multi-Year Support: Fetch the latest year, last N years, or all available history.
* 💾 Raw Data Mode: Option to retrieve pure XBRL data without calculations.
* 🛠️ CLI Tool: Includes a command-line tool for quick lookups.
* 📦 Zero Runtime Dependencies: Lightweight and fast (uses native fetch).

Installation

``bash
npm install nbb-client
`

Usage

$3

`typescript
import { NbbClient } from 'nbb-client';

const client = new NbbClient('YOUR_NBB_SUBSCRIPTION_KEY');

async function main() {
try {
// Fetch latest financials for a company (e.g., 0462.925.669)
const data = await client.getFinancials('0462925669');

console.log(Year: ${data.year});
console.log(Revenue: ${data.ratios.revenue.value});
console.log(Net Profit Margin: ${data.ratios.net_profit_margin.value});

// Access multilingual labels
console.log(data.ratios.net_profit_margin.label_en); // "Net Profit Margin"
console.log(data.ratios.net_profit_margin.label_fr); // "Marge bénéficiaire nette"

} catch (err) {
console.error(err);
}
}

main();
`

$3

To avoid hitting NBB rate limits and speed up repeated lookups, you can optionally provide a cache implementation. We provide a simple FileSystemCache, but you can implement the ICache interface for Redis, Memcached, etc.

`typescript
import { NbbClient, FileSystemCache } from 'nbb-client';

// Without cache (default)
// const client = new NbbClient('YOUR_KEY');

// With file-system cache
const client = new NbbClient('YOUR_KEY', {
cache: new FileSystemCache('./.nbb-cache')
});
`

$3

`typescript
// Fetch last 3 years
const history = await client.getFinancials('0462925669', { limit: 3 });

// Fetch ALL available years
const fullHistory = await client.getFinancials('0462925669', { all: true });
`

$3

If you don't need the calculated ratios:

`typescript
const raw = await client.getFinancials('0462925669', { includeRatios: false });
console.log(raw.raw['70']); // Access raw XBRL rubric 70 (Turnover)
`

CLI Usage

You can use the client directly from your terminal:

`bash

Fetch latest data

npx nbb-client 0462925669 --key YOUR_KEY

Fetch last 3 years

npx nbb-client 0462925669 --limit 3 --key YOUR_KEY

Output raw JSON

npx nbb-client 0462925669 --json --key YOUR_KEY
``

License

MIT