ynabber

package module
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2025 License: GPL-3.0 Imports: 7 Imported by: 0

README

Ynabber

Ynabber is a tool that reads and writes bank transactions from one or more sources (called readers) to one or more destinations (called writers). This makes it easier to pull in your bank transactions automatically and push them to personal finance apps like YNAB.

See subsection readers and writers for a list of supported banks and services.

Installation

You can use Go or Docker to install and run Ynabber. Choose whichever option you find more convenient.

# Install with Go
go install github.com/martinohansen/ynabber/cmd/ynabber@latest

# Install with Docker
docker pull ghcr.io/martinohansen/ynabber:latest

Usage

Ynabber is configured via environment variables. Below is an example setup for reading transactions from GoCardless (formerly known as Nordigen) and writing them to YNAB.

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

Then run Ynabber:

# Load environment variables from the file
set -a; . ./ynabber.env; set +a; ynabber

# Then run
ynabber

Or using Docker:

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

All valid config variables can be found here

Readers

Readers are how Ynabber fetches your transactions from the bank. Below are some tested examples. Generally, any bank supported by GoCardless (formerly known as Nordigen) should work:

Reader Bank Verified?
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

Writers tell Ynabber where to send the fetched transactions.

Writer Description
YNAB Pushes transactions to a YNAB budget
JSON Writes transactions as JSON to stdout (useful for testing)

Contributing

Pull requests are welcome! If you encounter a bug or have an idea for improvement, feel free to open an issue. We’d love your help in making Ynabber better for everyone!

Documentation

Index

Constants

View Source 
const DateFormat = "2006-01-02"

Variables

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

Functions

This section is empty.

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:"6h"`

	// 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 added in v0.6.0 

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

type Reader added in v0.7.0 

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 TransactionStatus added in v0.8.0 

type TransactionStatus string
const (
	Cleared    TransactionStatus = "cleared"
	Uncleared  TransactionStatus = "uncleared"
	Reconciled TransactionStatus = "reconciled"
)

func (*TransactionStatus) Decode added in v0.8.0 

func (cs *TransactionStatus) Decode(value string) error

Decode implements `envconfig.Decoder` for TransactionStatus

func (TransactionStatus) String added in v0.8.0 

func (cs TransactionStatus) String() string

type Writer added in v0.7.0 

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"`

	// Delay sending transaction to YNAB by this duration. This can be necessary
	// if the bank changes transaction IDs after some time. Default is 0 (no
	// delay).
	Delay time.Duration `envconfig:"YNAB_DELAY" default:"0"`

	// 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 TransactionStatus `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
	// contains filtered or unexported fields
}

func NewYnabber added in v0.8.2 

func NewYnabber(config *Config) *Ynabber

NewYnabber creates a new Ynabber instance

func (*Ynabber) Run added in v0.8.2 

func (y *Ynabber) Run()

Run starts Ynabber by reading transactions from all readers into a channel to fan out to all writers

Source Files

View all Source files

Directories

Path Synopsis
cmd
ynabber
reader
nordigen
writer
json
ynab

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.