ynabber

README

Ynabber

Ynabber sets out to read and write bank transactions from one or more sources (known as readers) to one or more destinations (known as writers).

For a list of supported see the readers and writers subsections.

Installation

Install Go and run go install to install binary

go install github.com/martinohansen/ynabber/cmd/ynabber@latest

Usage

Ynabber is configured with environment variables. To read from Nordigen (now known as GoCardless) and write to YNAB use these values:

cat <<EOT >> ynabber.env
# YNAB
YNAB_BUDGETID=<budget_id>
YNAB_TOKEN=<account token>
YNAB_ACCOUNTMAP={"<IBAN>": "<YNAB account ID>"}

# Nordigen
NORDIGEN_BANKID=<nordigen bank ID>
NORDIGEN_SECRET_ID=<nordigen secret ID>
NORDIGEN_SECRET_KEY=<nordigen secret key>
EOT

All valid config options can be found in the config.go file.

To read the environment variables from a file and run the binary one can use the declare command:

# Read environment variables from file and run ynabber
declare $(cat ynabber.env); ynabber

Or run the container and parse in the variables with Docker

docker run --env-file=ynabber.env ghcr.io/martinohansen/ynabber:latest

# To keep data persistent
docker run \
    --volume ${PWD}:/data \
    --env 'YNABBER_DATADIR=/data' \
    --env-file=ynabber.env \
    ghcr.io/martinohansen/ynabber:latest

Readers

Currently tested readers and verified banks, but any bank supported by Nordigen should work.

Reader	Bank
Nordigen[^1]	ALANDSBANKEN_AABAFI22	✅
	NORDEA_NDEADKKK	✅
	NORDEA_NDEAFIHH	✅
	NORWEGIAN_FI_NORWNOK1	✅
	S_PANKKI_SBANFIHH	✅

[^1]: Please open an issue if you have problems with a specific bank.

Writers

The default writer is YNAB (that's really what this tool is set out to handle) but we also have a JSON writer that can be used for testing purposes.

Writer	Description
YNAB	Pushes transactions to YNAB
JSON	Writes transactions to stdout in JSON format

Contributing

Pull requests are welcome.

Documentation

Index

• Constants
• Variables
• type Account
• type AccountMap
  • func (accountMap *AccountMap) Decode(value string) error
• type Config
• type Date
  • func (date *Date) Decode(value string) error
• type ID
• type Milliunits
  • func MilliunitsFromAmount(amount float64) Milliunits
  • func (m Milliunits) Negate() Milliunits
  • func (m Milliunits) String() string
• type Nordigen
• type Payee
  • func (p Payee) Strip(s []string) Payee
• type Reader
• type Transaction
• type Writer
• type YNAB
• type Ynabber

Constants

const DateFormat = "2006-01-02"

Variables

var ErrNotFound = errors.New("not found")

Types

type Account

type Account struct {
	ID   ID
	Name string
	IBAN string
}

type AccountMap

type AccountMap map[string]string

func (*AccountMap) Decode

func (accountMap *AccountMap) Decode(value string) error

Decode implements `envconfig.Decoder` for AccountMap to decode JSON properly

type Config

type Config struct {
	// DataDir is the path for storing files
	DataDir string `envconfig:"YNABBER_DATADIR" default:"."`

	// Debug prints more log statements
	Debug bool `envconfig:"YNABBER_DEBUG" default:"false"`

	// Interval is how often to execute the read/write loop, 0=run only once
	Interval time.Duration `envconfig:"YNABBER_INTERVAL" default:"5m"`

	// Readers is a list of sources to read transactions from. Currently only
	// Nordigen is supported.
	Readers []string `envconfig:"YNABBER_READERS" default:"nordigen"`

	// Writers is a list of destinations to write transactions to.
	Writers []string `envconfig:"YNABBER_WRITERS" default:"ynab"`

	// Reader and/or writer specific settings
	Nordigen Nordigen
	YNAB     YNAB
}

Config is loaded from the environment during execution with cmd/ynabber

type Date

type Date time.Time

func (*Date) Decode

func (date *Date) Decode(value string) error

Decode implements `envconfig.Decoder` for Date to parse string to time.Time

type ID

type ID string

type Milliunits

type Milliunits int64

func MilliunitsFromAmount

func MilliunitsFromAmount(amount float64) Milliunits

MilliunitsFromAmount returns a transaction amount in YNABs milliunits format

func (Milliunits) Negate

func (m Milliunits) Negate() Milliunits

Negate changes the sign of m to the opposite

func (Milliunits) String

func (m Milliunits) String() string

type Nordigen

type Nordigen struct {
	// BankID is used to create requisition
	BankID string `envconfig:"NORDIGEN_BANKID"`

	// SecretID is used to create requisition
	SecretID string `envconfig:"NORDIGEN_SECRET_ID"`

	// SecretKey is used to create requisition
	SecretKey string `envconfig:"NORDIGEN_SECRET_KEY"`

	// PayeeSource is a list of sources for Payee candidates, the first method
	// that yields a result will be used. Valid options are: unstructured, name
	// and additional.
	//
	//	* unstructured: uses the `RemittanceInformationUnstructured` field
	//	* name: uses either the either `debtorName` or `creditorName` field
	//	* additional: uses the `AdditionalInformation` field
	PayeeSource []string `envconfig:"NORDIGEN_PAYEE_SOURCE" default:"unstructured,name,additional"`

	// PayeeStrip is a list of words to remove from Payee. For example:
	// "foo,bar"
	PayeeStrip []string `envconfig:"NORDIGEN_PAYEE_STRIP"`

	// TransactionID is the field to use as transaction ID. Not all banks use
	// the same field and some even change the ID over time.
	//
	// Valid options are: TransactionId, InternalTransactionId
	TransactionID string `envconfig:"NORDIGEN_TRANSACTION_ID" default:"TransactionId"`

	// RequisitionHook is a exec hook thats executed at various stages of the
	// requisition process. The hook is executed with the following arguments:
	// <status> <link>
	RequisitionHook string `envconfig:"NORDIGEN_REQUISITION_HOOK"`

	// RequisitionFile overrides the file used to store the requisition. This
	// file is placed inside the YNABBER_DATADIR.
	RequisitionFile string `envconfig:"NORDIGEN_REQUISITION_FILE"`
}

Nordigen related settings

type Payee

type Payee string

func (Payee) Strip

func (p Payee) Strip(s []string) Payee

Strip removes the elements from s from the payee

type Reader

type Reader interface {
	Bulk() ([]Transaction, error)
}

type Transaction

type Transaction struct {
	Account Account `json:"account"`
	ID      ID      `json:"id"`
	// Date is the date of the transaction in UTC time
	Date   time.Time  `json:"date"`
	Payee  Payee      `json:"payee"`
	Memo   string     `json:"memo"`
	Amount Milliunits `json:"amount"`
}

type Writer

type Writer interface {
	Bulk([]Transaction) error
}

type YNAB

type YNAB struct {
	// BudgetID for the budget you want to import transactions into. You can
	// find the ID in the URL of YNAB: https://app.youneedabudget.com/<budget_id>/budget
	BudgetID string `envconfig:"YNAB_BUDGETID"`

	// Token is your personal access token as obtained from the YNAB developer
	// settings section
	Token string `envconfig:"YNAB_TOKEN"`

	// AccountMap of IBAN to YNAB account IDs in JSON. For example:
	// '{"<IBAN>": "<YNAB Account ID>"}'
	AccountMap AccountMap `envconfig:"YNAB_ACCOUNTMAP"`

	// FromDate only import transactions from this date and onward. For
	// example: 2006-01-02
	FromDate Date `envconfig:"YNAB_FROM_DATE"`

	// Set cleared status, possible values: cleared, uncleared, reconciled .
	// Default is uncleared for historical reasons but recommend setting this
	// to cleared because ynabber transactions are cleared by bank.
	// They'd still be unapproved until approved in YNAB.
	Cleared string `envconfig:"YNAB_CLEARED" default:"uncleared"`

	// SwapFlow changes inflow to outflow and vice versa for any account with a
	// IBAN number in the list. This maybe be relevant for credit card accounts.
	//
	// Example: "DK9520000123456789,NO8330001234567"
	SwapFlow []string `envconfig:"YNAB_SWAPFLOW"`
}

YNAB related settings

type Ynabber

type Ynabber struct {
	Readers []Reader
	Writers []Writer
}