txcategorizer

Parse and categorize Norwegian bank transaction exports (DNB and Valle) into structured, fully typed data. CSV in, transactions out.

NPM Package

Install

pnpm add txcategorizer

Basic usage

import { processTransactions } from 'txcategorizer';

const result = processTransactions(csvContent, 'dnb');

csvContent can be a string or ArrayBuffer. Buffers are decoded with the bank's encoding automatically — Valle exports use Windows-1252, so pass the raw ArrayBuffer and the library handles it.

// Reading a file in Node.js
import { readFileSync } from 'fs';

const buffer = readFileSync('transactions.csv').buffer;
const result = processTransactions(buffer, 'valle');

Each result item is a Transaction:

type Transaction = {
    date: string; // "2025-12-31"
    amount: number; // negative = expense, positive = income
    merchant: string; // "REMA 1000"
    type: TransactionType; // "Varekjøp"
    category: Category; // "Dagligvare"
    counterparty?: string; // "Sofie Krukhaug" (for transfers/Vipps)
    valuta?: Valuta; // only present for non-NOK transactions
    raw?: string; // original description (debug mode only)
};

Options

All options are optional — the defaults work out of the box.

const result = processTransactions(csvContent, 'dnb', {
    merchantAliases: { rema: 'REMA 1000' },
    categoryKeywords: { Dagligvare: ['rema', 'kiwi', 'extra'] },
    ownAccounts: ['1234 56 78901'],
    cityPrefixes: ['Oslo', 'Bergen'],
    nWordMerchants: { Burger: 2, Salt: 3 },
    corporateSuffixPattern: /\s+(as|asa)\b.*$/i,
    debug: false,
});

| Option | Type | Description | | ------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- | | merchantAliases | MerchantAliases | Normalize raw merchant names. Keys are lowercase prefix matches. | | categoryKeywords | CategoryKeywords | Keywords (word-boundary matched, escaped as literal text) mapped to categories. | | ownAccounts | string[] | Account numbers that identify transfers to your own accounts → type becomes Kontoregulering. | | cityPrefixes | string[] | City names that prefix merchant names in card transactions (e.g. "Gjøvik Specsave"). | | nWordMerchants | Record<string, number> | Multi-word merchant names. Key = first word, value = total word count to capture. | | corporateSuffixPattern | RegExp | Pattern to strip from company names (e.g. " As", " Asa"). | | extractionRules | MerchantRule[] | Fully replace the built-in extraction rules with your own. | | debug | boolean | Adds raw field with original description to each transaction and logs skipped rows. |

Extending defaults

Options replace the defaults. To add entries on top of them, spread the exported defaults:

import {
    processTransactions,
    defaultCityPrefixes,
    defaultNWordMerchants,
    defaultMerchantAliases,
} from 'txcategorizer';

const result = processTransactions(csvContent, 'dnb', {
    cityPrefixes: [...defaultCityPrefixes, 'Hamar', 'Lillehammer'],
    nWordMerchants: { ...defaultNWordMerchants, Little: 2 },
    merchantAliases: { ...defaultMerchantAliases, rema: 'REMA 1000' },
});

All defaults are exported: defaultMerchantAliases, defaultCategoryKeywords, defaultCityPrefixes, defaultNWordMerchants, defaultCorporateSuffixPattern, and defaultOptions.

Custom extraction rules

For full control over merchant extraction, provide your own extractionRules. Each rule has a match predicate and an extract function; the first matching rule wins:

import { processTransactions, type MerchantRule } from 'txcategorizer';

const myRules: MerchantRule[] = [
    {
        match: ({ type }) => type === 'Varekjøp',
        extract: ({ description }) => ({
            merchant: description.split(/\s+/)[0] ?? '',
        }),
    },
];

const result = processTransactions(csvContent, 'dnb', {
    extractionRules: myRules,
});

To build on the built-in rules instead of replacing them, use createMerchantRules:

import { createMerchantRules } from 'txcategorizer';

const rules = [...myRules, ...createMerchantRules()];

Pipeline steps

The individual pipeline stages are exported for advanced use:

import { parseCsv, extractMerchants, categorizeTransactions, resolveOptions } from 'txcategorizer';

const options = resolveOptions({ debug: true });
const raw = parseCsv(csvText, 'dnb', options); // RawTransaction[]
const extracted = extractMerchants(raw, options); // ExtractedTransaction[]
const transactions = categorizeTransactions(extracted, options.categoryKeywords); // Transaction[]

Categories

import { CATEGORIES, type Category } from 'txcategorizer';

The 21 built-in categories:

Dagligvare · Mat ute · Hjem · Underholdning · Gaming · Abonnement · Netthandel · Helse · Kosmetikk · Klær · Kreditt · Transport · Bil · Bolig · Boutgifter · Forsikring · Overføring · Inntekt · Sparing · Diverse · Annet

Transactions that don't match any keyword fall back to Annet. Transaction types are exported the same way as TRANSACTION_TYPES / TransactionType, and supported banks as BANKS / Bank.

Supported banks

| Bank | Format | Encoding | | ----- | ------------------- | ------------ | | DNB | CSV (; delimited) | UTF-8 | | Valle | CSV (; delimited) | Windows-1252 |

A standalone decodeWindows1252(buffer) helper is also exported.

Development

pnpm test       # run tests
pnpm typecheck  # type-check src + tests
pnpm build      # emit dist/

The tests and the documentation were drafted with the help of an LLM (Claude)