Kontonummer


> [!IMPORTANT]
> Currently implements the 2024-02-22 version of the
> Bank Account Numbers in Swedish Banks
> specification from Bankgirot.

This is a reimagination of jop-io/kontonummer.js
with some additional goals:

- Provide a similar API to Personnummer
- Stretch goal: Calculate IBAN (and BIC/SWIFT-code)
- Stretch goal: Handle BankGirot and PlusGirot numbers

Some Code (c) Jonas Persson and
Tobbe Lundberg which they have gracefully released
under a MIT license. See LICENSE

This implementation is written in TypeScript but the following specification
should be applicable to other languages as well. But some language specific
modifications may be required.

Important Caveat

As explained in the research section below there are some bank
account numbers that are impossible to validate (as they do not have a check
digit) that are indistinguishable from validatable accounts. I recommend using
this library on form input fields, but do not prevent form submission if the
account number is reported as invalid. A good idea would be something like a
warning saying "There is a chance this is not a valid bank account number;
you may want to double-check."

Specification [v1]

$3

The package should include a class that which should be the return value of parse

``typescript
class Kontonummer {
constructor (sortingCode: string | number, accountNumber: string | number, options?: InitOptions)
constructor (sortingCodeAndAccountNumber: string | number, options?: InitOptions)
}
`

- sortingCode (sv. clearing nummer) should be one of the following formats
- SSSS
- SSSS-C
- accountNumber the allowed length varies, further explained in section
Account Number
White-space should be allowed in any position. Basically, only characters
matching the regex /\d/ should be taken into consideration; all other
characters should be discarded.
- sortingCodeAndAccountNumber should be one of the following formats
(where S is sorting code, A is account number and C is a check digit.
White-space should be allowed in any position. Basically, only characters
matching the regex /\d/ should be taken into consideration; all other
characters should be discarded.
- SSSS,AC
- SSSSAC
- S-C,AC
- S-CAC
- S-C,A-C
- S-CA-C
- etc.

$3

- mode: 'strict' | 'semi' | 'lax'
- strict should validate sorting code, account number length and account
number check digit. Should throw if any of these checks fail.
- semi should do strict checks for type 1 account numbers (4+7) but lax
checks for type 2 account numbers.
- lax should not throw if the check digit of the account number cannot be
validated. Should instead set the valid property to false if the check
digit or length is invalid. Should still throw for invalid sorting codes.

$3

The class should expose the following properties once initialised

`typescript
class Kontonummer {
readonly bankName: string
readonly sortingCode: string
readonly accountNumber: string
readonly type: 1 | 2
readonly comment: 1 | 2 | 3
readonly valid: boolean // only relevant in lax mode
}
`

$3

All methods except for validate should throw an exception or return an error
as a second return value. Error handling may be different depending on language.
The exception/error class should be prefixed with Kontonummer.

$3

The class should include a static parse method that creates a new instance of
the class. It should take the same arguments as the class constructor. This
function should also be an exported standalone method of the package.

Pseudocode:

`typescript
class Kontonummer {
static parse (...args) {
return new Kontonummer(...args)
}
}

export const parse = Kontonummer.parse
`

$3

The class should include a static validate method that attempts to parse the
provided input and returns a boolean that indicates if it succeeded. validate
should not accept any options. This function should also be an exported
standalone method of the package.

Pseudocode:

`typescript
class Kontonummer {
validate (sortingCode, accountNumber)
validate (sortingCodeAndAccountNumber) {
try {
new Kontonummer(sortingCode, accountNumber)
return true
} catch {
return false
}
}
}

export const validate = Kontonummer.validate
`

$3

Format key:
- S: Sorting Code
- A: Account number
- C: Check digit
- K: IBAN check digit
- B: IBAN bank code

The class should include a public format method that returns the sortingCode
and accountNumber in one string. Some different formats should be available.
If no argument is provided it should default to numeric.

`typescript
type Format = 'numeric' | 'pretty'
type Part = 'full' | 'sortingCode' | 'accountNumber'

class Kontonummer {
format (format?: Format = 'numeric', part?: Part = 'full'): string
}
`

| Name | Format |
| ---- | ---- |
| numeric
_(default)_ | S[C]AC
where the account number is padded to the appropriate max length depending on account type |
| pretty | Depends on type and bank, see research below |

[]` brackets marks optional

Research

Moved to swantzter.se where I plan to publish research on other topics as well